People and contacts in EWS in Exchange

Learn about personas, the Unified Contact Store, and how to work with contacts by using the EWS Managed API or EWS in Exchange.

Contacts are items in Exchange that store information about an individual, group, or organization. Contacts can include names and email addresses, and other information, including IM addresses, physical addresses, birthdays, family information, and a photo or image that represents the contact.

Contact information is stored in one of two places:

• Active Directory Domain Services (AD DS), if the contact is within the organization.

• The Contacts folder or another folder in a user's mailbox, if the contact is outside the organization.

Multiple contact items can represent a single individual. Exchange uses personas to help bring these different contact items together. A persona is an aggregation of contact information for the same individual from different sources. In addition to contact information in Exchange, personas can also be aggregated from information in the recipient cache for the mailbox, a hidden folder for IM contacts called QuickContacts, and from third-party data sources. The Unified Contact Store in Exchange enables IM clients to use this aggregation; the only difference is that the Unified Contact Store does not aggregate information from AD DS, as shown in Figure 1.

Figure 1. Contact information sources for personas and for the Unified Contact Store

Table 1. EWS Managed API methods and EWS operations for working with contacts

If you want to…	Use this EWS Managed API method	Use this EWS operation
Create a new contact	Instantiate a new Contact object, and use Contact.Save	CreateItem
Copy a contact	Contact.Copy	CopyItem
Move a contact	Contact.Move	MoveItem
Update an existing contact	Contact.Bind and Contact.Update	UpdateItem
Delete a contact	Contact.Bind and Contact.Delete	DeleteItem
Search for a contact	ExchangeService.FindItems	FindItem
Search for people	N/A	FindPeople
Expand a distribution group	ExchangeService.ExpandGroup	ExpandDL
Resolve an ambiguous name	ExchangeService.ResolveName	ResolveNames
Get a persona	N/A	GetPersona
Work with contact photos	Contact.SetContactPicture, Contact.GetContactPictureAttachment, or Contact.RemoveContactPicture	GetUserPhoto or GetAttachment

Personas

Until recently, contacts were commonly stored in a single location — typically, on an email client. Today, it is becoming more common to store contacts in many different locations, such as on a phone, on a social networking site, in a Contacts folder in an Exchange mailbox, or in an organization's directory service. With the proliferation of contact information, it's possible that multiple contacts that represent the same person contain different information; for example, one contact might include a business phone number and another a personal phone number, or a contact stored in a Contacts folder might have a different name than the contact for the same person that is stored on your phone.

In Exchange Online, Exchange Online as part of Office 365, and on-premises versions of Exchange starting with Exchange 2013, contacts from different sources that represent the same person are associated with one another, similar to the way that email messages are aggregated into conversations, by means of a common link ID. When aggregated contact information is returned by an Exchange server, it includes a set of attributes for each contact, such as a source folder, a display name, an ID, and a source ID. The sum of the properties and attributes returned is known as a persona, and the set of properties returned is referred to as the persona's shape.

Because the information that makes up a persona is not stored in a single location, and because that information can change at any time, a persona is created only when you make a request to an Exchange server. You use the FindPeople EWS operation to make a persona search request. Your request can include a sort order, and can be filtered according to a query string to help you find the correct persona by ordering and filtering the results. For example, you can retrieve the display name and a set of all email addresses that are associated with a specific contact from the Contacts folder, a Hotmail account, a LinkedIn account, and a company's directory service, or you can retrieve a set of all personas that have IM addresses. The linking of contacts into personas is automatic based on an algorithm that recognizes a relationship between contacts stored on various devices.

Note

The EWS Managed API does not implement this functionality.

Table 2. EWS operations for working with personas

Operation name	Description
FindPeople	Returns all available personas from a specified contacts folder or retrieves contacts that match a specified query string.
GetPersona	Returns a set of properties associated with a specific persona, such as all the IM addresses or display names for a specified persona ID.

You can use the GetPersona and FindPeople operations to efficiently retrieve contact information from multiple sources. Because all items related to a persona are associated with a link ID, you can use these operations in a wide variety of applications that use contact data. The following are some examples:

• A mobile phone app that uses the GetPersona operation when a user calls a contact, and then offers additional phone numbers to call if no one answers.

• An application that uses the FindPeople operation to scan Inbox messages for email addresses to determine whether they are found in an existing persona. Addresses that are not already associated with a persona can be used to create sales leads or list all recent communications with the person represented by that persona.

• A mail app for Outlook that offers different salutations based on whether correspondence is formal or informal. Formal salutations are supplied by the display names from the directory service and informal salutations come from the display name that originates in social network contacts.

Unified Contact Store

Personas aren't just limited to an email client. If you're developing an IM client, you might ask yourself any or all of the following:

• How can I provision Lync client applications with a default set of IM contact items?

• How do I manage IM contact and group lists?

• How do I manage custom Lync client access to IM contacts and IM groups?

The Unified Contact Store works behind the scenes in Exchange to aggregate contact data from Exchange and other sources into a single entity, or persona. Although the EWS operations that you use to access the Unified Contact Store are specific to IM contacts, You can use the Unified Contact Store in Exchange to work with personas in all types of applications. Keep in mind that the Unified Contact Store cannot access contact data AD DS.

IM contacts are stored in a hidden folder called QuickContacts. You can use the AddNewImContactToGroup and AddImContactToGroup operations to add contacts to groups that are stored in this hidden folder. And because you can use the Unified Contact Store to group IM contacts, you can access and update groups of contacts more easily.

Note

The EWS Managed API does not implement this functionality.

Table 3. EWS operations for accessing the Unified Contact Store

Operation name	Description
AddNewImContactToGroup	Adds a new IM contact to an IM group, up to a maximum of 1000 contacts.
AddImContactToGroup	Adds an existing IM contact to an IM group, up to a maximum of 1000 contacts.
AddImGroup	Adds a new IM group, up to a maximum of 64 groups.
AddDistributionGroupToImList	Adds a new distribution group to an IM group, up to a maximum of 64 groups.
GetImItemList	Retrieves a list of IM groups and IM contact personas.
GetImItems	Retrieves information about specific IM groups and IM contact personas.
RemoveContactFromImList	Removes a contact from an IM group.
RemoveImContactFromGroup	Removes an IM contact from an IM group.
RemoveDistributionGroupFromImList	Removes a distribution group from an IM group.
RemoveImGroup	Removes an IM group.
SetImGroup	Changes the display name of an IM group.

In this section

• Process contacts in batches by using EWS in Exchange

• Resolve ambiguous names by using EWS in Exchange 2013

• Get user photos by using EWS in Exchange

See also

• Develop web service clients for Exchange

• Start using web services in Exchange

• EWS client design overview for Exchange