1. Work with contacts

Get contacts

Version:

Use the client.Get<Contact>() or client.GetAsync<Contact> method to retrieved by ID or by an identifier. You can retrieve a single contact or a batch of contacts.

Get contact by ID

The following example demonstrates how to retrieve a single contact by ID:

using Sitecore.XConnect.Operations;
using System;
using System.Threading.Tasks;
using Sitecore.XConnect;
using Sitecore.XConnect.Client;

namespace Documentation
{
    public class GetContact
    {
        // Async example
        public async void ExampleAsync()
        {
            using (Sitecore.XConnect.Client.XConnectClient client = Sitecore.XConnect.Client.Configuration.SitecoreXConnectClientConfiguration.GetClient())
            {
                try
                {
                    var reference = new Sitecore.XConnect.ContactReference(Guid.Parse("B9814105-1F45-E611-82E6-34E6D7117DCB"));

                    Task<Sitecore.XConnect.Contact> contactTask = client.GetAsync<Sitecore.XConnect.Contact>(reference, new ContactExecutionOptions(new
ContactExpandOptions() { });

                    Contact contact = await contactTask;
                }
                catch (XdbExecutionException ex)
                {
                    // Manage exceptions
                }
            }
        }

        // Sync example
        public void Example()
        {
            using (Sitecore.XConnect.Client.XConnectClient client = Sitecore.XConnect.Client.Configuration.SitecoreXConnectClientConfiguration.GetClient())
            {
                try
                {
                    var reference = new Sitecore.XConnect.ContactReference(Guid.Parse("B9814105-1F45-E611-82E6-34E6D7117DCB"));

                    Contact contact = client.Get<Contact>(reference, new ContactExecutionOptions(new
ContactExpandOptions() { });
                }
                catch (XdbExecutionException ex)
                {
                    // Manage exceptions
                }
            }
        }
    }
}

Get contact by identifier

The following examples demonstrate how to retrieve a contact by an identifier. Use the same method for both known and anonymous identifiers. Refer to the contacts overview topic for more information about identifiers

Note

Both source and identifier are case sensitive.

using Sitecore.XConnect;
using System.Threading.Tasks;
using Sitecore.XConnect.Client;

namespace Documentation
{
    public class GetContactByIdentifier
    {
        // Async example
        public async void ExampleAsync()
        {
            using (XConnectClient client = Sitecore.XConnect.Client.Configuration.SitecoreXConnectClientConfiguration.GetClient())
            {
                try
                {
                    var reference = new IdentifiedContactReference("twitter", "myrtlesitecore");

                    Task<Contact> contactTask = client.GetAsync<Contact>(reference, new ContactExecutionOptions(new
ContactExpandOptions() { }));

                    Contact contact = await contactTask;
                }
                catch (XdbExecutionException ex)
                {
                    // Manage exceptions
                }
            }
        }

        // Sync example
        public void Example()
        {
            using (XConnectClient client = Sitecore.XConnect.Client.Configuration.SitecoreXConnectClientConfiguration.GetClient())
            {
                try
                {
                    var reference = new IdentifiedContactReference("twitter", "myrtlesitecore");

                    Contact contact = client.Get<Contact>(reference, new ContactExecutionOptions(new
ContactExpandOptions() { }));
                }
                catch (XdbExecutionException ex)
                {
                    // Manage exceptions
                }
            }
        }
    }
}

Get contact by alias identifier

All contacts have an alias identifier that consist of a GUID and source defined by Sitecore.XConnect.Constants.AliasIdentifierSource.

using Sitecore.XConnect;
using System.Threading.Tasks;
using Sitecore.XConnect.Client;

namespace Documentation
{
    public class GetContactByAliasIdentifier
    {
        // Async example
        public async void ExampleAsync()
        {
            using (XConnectClient client = Sitecore.XConnect.Client.Configuration.SitecoreXConnectClientConfiguration.GetClient())
            {
                try
                {
                    var reference = new IdentifiedContactReference(Sitecore.XConnect.Constants.AliasIdentifierSource, "1c59d6f4-1ea6-4219-887b-d8f5a0b8104a");

                    Task<Contact> contactTask = client.GetAsync<Contact>(reference, new ContactExecutionOptions(new
ContactExpandOptions() { }));

                    Contact contact = await contactTask;
                }
                catch (XdbExecutionException ex)
                {
                    // Manage exceptions
                }
            }
        }

        // Sync example
        public void Example()
        {
            using (XConnectClient client = Sitecore.XConnect.Client.Configuration.SitecoreXConnectClientConfiguration.GetClient())
            {
                try
                {
                    var reference = new IdentifiedContactReference(Sitecore.XConnect.Constants.AliasIdentifierSource, "1c59d6f4-1ea6-4219-887b-d8f5a0b8104a");

                    Contact contact = client.Get<Contact>(reference, new ContactExecutionOptions(new
ContactExpandOptions() { }));
                }
                catch (XdbExecutionException ex)
                {
                    // Manage exceptions
                }
            }
        }
    }
}
Tip

Use the .GetAlias() extension on the Contact class to retrieve a contact’s alias identifier.

Get multiple contacts

You can use .GetAsync<Contact>() and .Get<Contact>() methods to retrieve multiple contacts by passing in an array of contact references. Contacts are returned as a single batch. As shown in the following example, it is possible to retrieve contacts using a mixture of IDs and identifiers:

using Sitecore.XConnect.Operations;
using System;
using System.Collections.Generic;
using Sitecore.XConnect;
using Sitecore.XConnect.Client.Configuration;
using Sitecore.XConnect.Client;

namespace Documentation
{
    public class GetMultipleContacts
    {
        // Async example
        public async void AsyncExample()
        {
            using (XConnectClient client = SitecoreXConnectClientConfiguration.GetClient())
            {
                try
                {
                    var references = new List<IEntityReference<Contact>>()
                    {
                        // Contact ID
                        new ContactReference(new Guid("{A2814105-1F45-E611-52E6-34E6D7117DCB}")),
                        // Known identifier
                        new IdentifiedContactReference("twitter", "myrtlesitecore"),
                        // Anonymous identifier
                        new IdentifiedContactReference("adnetwork", "AB973934540244")
                    };

                    var contactsTask = client.GetAsync<Contact>(references, new ContactExecutionOptions(new
ContactExpandOptions() { }));

                    IReadOnlyCollection<IEntityLookupResult<Contact>> contactsResult = await contactsTask;

                    foreach (var result in contactsResult)
                    {
                        if (result.Exists)
                        {
                            Contact contact = result.Entity;
                        }
                    }

                }
                catch (XdbExecutionException ex)
                {
                    // Manage exceptions
                }
            }
        }

        // Sync example
        public void Example()
        {
            using (XConnectClient client = SitecoreXConnectClientConfiguration.GetClient())
            {
                try
                {
                    var references = new List<IEntityReference<Contact>>()
                    {
                        // Contact ID
                        new ContactReference(new Guid("{A2814105-1F45-E611-52E6-34E6D7117DCB}")),
                        // Known identifier
                        new IdentifiedContactReference("twitter", "myrtlesitecore"),
                        // Anonymous identifier
                        new IdentifiedContactReference("adnetwork", "AB973934540244")
                    };

                    IReadOnlyCollection<IEntityLookupResult<Contact>> contacts = client.Get<Contact>(references, new ContactExecutionOptions(new
ContactExpandOptions() { }));

                    foreach (var result in contacts)
                    {
                        if (result.Exists)
                        {
                            Contact contact = result.Entity;
                        }
                    }

                }
                catch (XdbExecutionException ex)
                {
                    // Manage exceptions
                }
            }
        }
    }
}

xConnect returns a IEntityLookupResult<Contact> for each operation even if the contact was not found. If the contact exists, the Exists property will be set to true and the contact can be accessed via the Entity property. If the contact exists but could not be retrieved, inspect the Exception property for more information.

Note

If multiple contact references refer to the same contact, xConnect cannot consolidate the list, and returns the contact multiple times.

By default, contacts are returned without facets or related interactions. Use expand options to determine which facets and which range of related interactions should be returned.

If you have suggestions for improving this article, let us know!