---
title: "xConnect Client API overview"
slug: "xconnect-client-api-overview"
abstract: "An overview of the xConnect Client API (C#)."
---
# xConnect Client API overview

The xConnect Client API is a portable C# library that allows trusted clients to create, read, update, and search contacts and interactions over HTTPS. The following example demonstrates [how to retrieve an xConnect client in a Sitecore context](https://doc.sitecore.com/xp/en/developers/100/sitecore-experience-platform/instantiate-client-in-a-sitecore-context.html "Instantiate client in a Sitecore context") and retrieve a single contact by ID:

```csharp
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())
            {
                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 Sitecore.XConnect.ContactExecutionOptions(new Sitecore.XConnect.ContactExpandOptions() { }));

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

```

> [!note]
> 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](https://doc.sitecore.com/xp/en/developers/100/sitecore-experience-platform/web-tracking.html "Web tracking") documentation for more information about to track contacts during a web session.

## Asynchronous and synchronous extension methods

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

| Asynchronous method | Synchronous method | Notes |
| --- | --- | --- |
| `GetAsync()` | `Get()` |  |
| `SubmitAsync()` | `Submit()` | Synhronous submit does not have a timeout overload. |
| `GetBatchEnumerator()` | `GetBatchEnumeratorSync()` |  |
| `ToSearchResults()` | N/A | A synchronous version of this extension is not currently available. |
| `InitializeAsync()` | `Initialize()` |  |

### Methods without a synchronous extension

If there is no synchronous version of a method, use the `SuspendContextLock()` method around the asynchronous call as shown in the following example:

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

```

> [!important]
> Do not call `.Wait()`, `.Result`, `ConfigureAwait(false).GetAwaiter().GetResult()`, or similar on tasks returned from the async API.

The following extension methods do not have a synchronous counterpart:

- `.FirstOrDefault()`
- `.First()`
- `.Single()`
- `.SingleOrDefault()`
- `.Count()`

## Batching operations

The xConnect Client API supports [batching xConnect operations](https://doc.sitecore.com/xp/en/developers/100/sitecore-experience-platform/batching-xconnect-operations.html "Batching xConnect operations"). Batches of operations are serialized, sent to xConnect over HTTPS, and deserialized by the xConnect service layer. In the following example, the `AddContact()` extension adds two `AddContactOperation` operations to the client before submitting both operations in a single batch:

```

var firstContact = new Contact();
client.AddContact(firstContact);

var secondContact = new Contact();
client.AddContact(secondContact);

await client.SubmitAsync();

```

### Confirming that a batch was saved to the xDB Collection database

After calling `client.Submit()`/`client.SubmitAsync()`, you can use the `client.LastBatch` property to see a list of the operations that were included in the batch. Data is available in the xDB Collection database for any operation where the value of the `Status` property is `Succeeded`. See [Get operation results](https://doc.sitecore.com/xp/en/developers/100/sitecore-experience-platform/get-operation-results.html "Get operation results") for more information.

### Confirming that a batch was indexed

The xConnect Search Indexer updates the xDB index after changes have been saved to the xDB Collection database. See [Batch indexing](https://doc.sitecore.com/xp/en/developers/100/sitecore-experience-platform/batch-indexing.html "Batch indexing") for more information about how to confirm that a batch has been indexed.

## Anticipating exceptions

The xConnect Client API throws an exception if one or more operations fails. Wrap usage of the xConnect Client API in a `try/catch` statement and catch the `XdbExecutionException` or `XdbUnavailableException` as shown in the following example:

```csharp
using (XConnectClient client = Sitecore.XConnect.Client.Configuration.SitecoreXConnectClientConfiguration.GetClient())
{
        try
        {
            // GET or POST some data
        }
        catch (XdbExecutionException ex)
        {
            // Handle the exception
        }
}

```

For more information about exceptions and error handling in xConnect, see [Handling exceptions](https://doc.sitecore.com/xp/en/developers/100/sitecore-experience-platform/handling-exceptions.html "Handling exceptions").