Add identifiers
A contact identifier uniquely identifies a contact to external systems and can be added to new or existing contacts. New identifiers are available in the contact’s Identifiers collection as soon as the batch has been successfully submitted.
Add identifiers to a new contact
In the following example, a known identifier and an anonymous identifier are added to a new contact. You can pass identifiers into the Contact constructor or use the .AddContactIdentifier() method.
using Sitecore.XConnect;
using Sitecore.XConnect.Client;
using Sitecore.XConnect.Operations;
using System;
using System.Collections.Generic;
using System.Collections.ObjectModel;
namespace Documentation
{
public class GetContactIdentifiers
{
public async void ExampleAsync()
{
using (Sitecore.XConnect.Client.XConnectClient client = Sitecore.XConnect.Client.Configuration.SitecoreXConnectClientConfiguration.GetClient())
{
try
{
var contact = new Sitecore.XConnect.Contact(
new Sitecore.XConnect.ContactIdentifier("twitter", "myrtlesitecore", Sitecore.XConnect.ContactIdentifierType.Known)
);
client.AddContact(contact);
client.AddContactIdentifier(contact, new Sitecore.XConnect.ContactIdentifier("ad-network", "ABC123456", Sitecore.XConnect.ContactIdentifierType.Anonymous));
await client.SubmitAsync();
}
catch (XdbExecutionException ex)
{
// Manage exception
}
}
}
public void Example()
{
using (Sitecore.XConnect.Client.XConnectClient client = Sitecore.XConnect.Client.Configuration.SitecoreXConnectClientConfiguration.GetClient())
{
try
{
var contact = new Sitecore.XConnect.Contact(
new Sitecore.XConnect.ContactIdentifier("twitter", "myrtlesitecore", Sitecore.XConnect.ContactIdentifierType.Known)
);
client.AddContact(contact);
client.AddContactIdentifier(contact, new Sitecore.XConnect.ContactIdentifier("ad-network", "ABC123456", Sitecore.XConnect.ContactIdentifierType.Anonymous));
client.Submit();
}
catch (XdbExecutionException ex)
{
// Manage exception
}
}
}
}
}
You can use the .AddContactIdentifier method to add an identifier to a new contact.
Add identifiers to an existing contact
In the following example, an identifier is added to an existing contact using the .AddContactIdentifier() method.
using System;
using Sitecore.XConnect;
using Sitecore.XConnect.Client;
namespace Documentation
{
public class UpdateContact
{
// Async example
public async void ExampleAsync()
{
using (Sitecore.XConnect.Client.XConnectClient client = Sitecore.XConnect.Client.Configuration.SitecoreXConnectClientConfiguration.GetClient())
{
try
{
// Retrieve contact from xConnect first
var existingContactTask = client.GetAsync<Sitecore.XConnect.Contact>(new Sitecore.XConnect.IdentifiedContactReference("twitter", "myrtlesitecore"), new ContactExecutionOptions(new Sitecore.XConnect.ContactExpandOptions("SitecoreSkyFrequentFlyerInfo")));
Sitecore.XConnect.Contact existingContact = await existingContactTask;
if (existingContact != null)
{
client.AddContactIdentifier(existingContact, new Sitecore.XConnect.ContactIdentifier("twitter", "myrtlesitecore", Sitecore.XConnect.ContactIdentifierType.Known));
await client.SubmitAsync();
}
}
catch (Exception ex)
{
// Handle exceptions
}
}
}
// Sync
public void Example()
{
using (Sitecore.XConnect.Client.XConnectClient client = Sitecore.XConnect.Client.Configuration.SitecoreXConnectClientConfiguration.GetClient())
{
try
{
// Retrieve contact from xConnect first
Contact existingContact = client.Get<Sitecore.XConnect.Contact>(new Sitecore.XConnect.IdentifiedContactReference("twitter", "myrtlesitecore"), new ContactExecutionOptions(new Sitecore.XConnect.ContactExpandOptions("SitecoreSkyFrequentFlyerInfo")));
if (existingContact != null)
{
client.AddContactIdentifier(existingContact, new Sitecore.XConnect.ContactIdentifier("twitter", "myrtlesitecore", Sitecore.XConnect.ContactIdentifierType.Known));
client.Submit();
}
}
catch (Exception ex)
{
// Handle exceptions
}
}
}
}
}
Updating contact identifiers
Existing contact identifiers cannot be updated. Identifiers can only be removed and added. In the following example, an existing identifier is being removed using the .RemoveContactIdentifier() extension:
using Sitecore.XConnect;
using System;
using System.Threading.Tasks;
using System.Linq;
using Sitecore.XConnect.Client;
namespace Documentation
{
public class RemoveContactIdentifier
{
// 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<Contact> contactTask = client.GetAsync<Sitecore.XConnect.Contact>(reference, new ContactExecutionOptions(new Sitecore.XConnect.ContactExpandOptions() { }));
Sitecore.XConnect.Contact contact = await contactTask;
var identifierToRemove = contact.Identifiers.FirstOrDefault(x => x.Identifier == "sitecoremyrtle");
client.RemoveContactIdentifier(contact, identifierToRemove);
await client.SubmitAsync();
}
catch (XdbExecutionException ex)
{
// Manage exception
}
}
}
// Sync example
public void ExampleSync()
{
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<Sitecore.XConnect.Contact>(reference, new ContactExecutionOptions(new Sitecore.XConnect.ContactExpandOptions() { }));
var identifierToRemove = contact.Identifiers.FirstOrDefault(x => x.Identifier == "sitecoremyrtle");
client.RemoveContactIdentifier(contact, identifierToRemove);
client.Submit();
}
catch (XdbExecutionException ex)
{
// Manage exception
}
}
}
}
}
Impact of adding or removing contact identifiers
The Contact ID (GUID) is the authoritative identity in xConnect. When you add a new identifier to an existing contact, the contact’s internal Contact ID (GUID) does not change. Analytic data for interactions, list membership, marketing automation enrollment, contact facets (including preferences) remain intact. The new identifier becomes immediately available for resolving the contact from external systems.
When you remove an existing identifier, the identifier does not delete the contact and historical interactions and analytics are not modified. Furthermore, the marketing automation plan enrollment and list membership are preserved.
We recommend that you do not remove identifiers that are still actively used by external systems, such as forms, login flows, EXM, and integrations. Systems that rely on the identifier to resolve the contact might fail once the identifier is removed, which could cause identity fragmentation. Removing an identifier can indirectly impact future tracking attribution, analytics reporting consistency, list membership accuracy, marketing automation continuity, and marketing preference enforcement (for example, unsubscribe being applied to the wrong contact).