Sitecore Experience Platform

xConnect Client API overview

The xConnect Client API is a portable web API that allows trusted clients to create, read, update, and search contacts and interactions over HTTPS. The xConnect Client API implements the oData protocol. The following example demonstrates how to retrieve an instance of the client in a Sitecore context and add a single contact:

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

namespace Documentation
    public class GetContact
        // Async example
        public async void ExampleAsync()
            using (Sitecore.XConnect.Client.XConnectClient client = Sitecore.XConnect.Client.Configuration.SitecoreXConnectClientConfiguration.GetClient())
                    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 Sitecore.XConnect.ContactExpandOptions() { });

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

The xConnect Client API is the only way to work with experience data. You cannot access the collection database or search index directly, and you should not use the ContactRepository and ContactManager classes in a non-tracking context.


The xConnect Client API does not replace the tracker. However, the tracker relies on the xConnect Client API to read and write data. Refer to the web tracking documentation for more information about to track contacts during a web session.

Asynchronous and synchronous extension methods

The xConnect Client API has is asynchronous, but there are synchronous versions of most extension methods available in Sitecore.XConnect.Client.XConnectSynchronousExtensions.








Synhronous submit does not have a timeout overload.





A synchronous version of this extension is not currently available.



Methods without a synchronous extension

Do not call .Wait(), .Result, ConfigureAwait(false).GetAwaiter().GetResult(), or similar on tasks returned from the async API. If there is no synchronous extension method, use the SuspendContextLock() method around the asynchronous call:

Sitecore.XConnect.Client.XConnectSynchronousExtensions.SuspendContextLock(client.Contacts.Where(c => c.Identifiers.Any(t => t.IdentifierType == Sitecore.XConnect.ContactIdentifierType.Known)).Count);Any(t => 

Examples of extension methods that do not have a synchronous counterpart include:

  • .FirstOrDefault()

  • .First()

  • .Single()

  • .SingleOrDefault()

  • .Count()

Anticipating exceptions

The xConnect Client API will throw an exception if one or more operations fails. Wrap usage of the xConnect Client API in a try/catch statement and catch the XdbExecutionException.

using (XConnectClient client = Sitecore.XConnect.Client.Configuration.SitecoreXConnectClientConfiguration.GetClient())
            // GET or POST some data
        catch (XdbExecutionException ex)
            // Do something

For more information about exceptions and error handling in xConnect, see Handling exceptions.

Batching operations

The xConnect Client API supports batching. Batches of operations are serialized, sent to xConnect over HTTPS, and deserialized by the xConnect service layer. In the following example, the .AddContact extension method is used to add two AddContactOperation operations to the client before submitting both operations in a single batch:

Consider the following example:

var firstContact = new Contact();

var secondContact = new Contact();

await client.SubmitAsync();

For more information about batching in xConnect, see Batch indexing.