Windows Live Contacts API: Field and Depth Filtering

Switch View

Field and Depth Filtering

Collapse All

Live Services SDK

Windows Live Contacts supports predefined filters and custom filters. Filters define the selection of entities or fields that you are interested in. A filter is similar to a SQL SELECT clause, in which you specify the columns that you want.

Predefined filters

The following predefined filters are available in the Windows Live Contacts API and are added to the request URL e.g. &filter=Hotmail

Name	Value
Hotmail	LiveContacts(Contact(ID,CID,WindowsLiveID,AutoUpdateEnabled, AutoUpdateStatus,Profiles,Email,Phone,Location,URI),Tag)
MessengerServer	LiveContacts(Contact(ID,CID,WindowsLiveID,AutoUpdateEnabled, AutoUpdateStatus,Profiles(Personal),Email,Phone),Tag)
Messenger	LiveContacts(Contact(ID,CID,WindowsLiveID,AutoUpdateEnabled, AutoUpdateStatus,Profiles,Email,Phone),Tag)
Phone	LiveContacts(Contact(ID,CID,WindowsLiveID,AutoUpdateEnabled, AutoUpdateStatus,Profiles(Personal(FirstName,LastName)),Email,Phone, Location),Tag)
MinimalPhone	LiveContacts(Contact(ID,WindowsLiveID,Profiles(Personal( NameToFileAs,FirstName,LastName)),Email,Phone),Tag)
MapPoint	LiveContacts(Contact(ID,WindowsLiveID,Profiles(Personal( NameToFileAs,FirstName,LastName)),Location))

Custom filters

If a predefined filter does not return the data that you want, you can define a custom filter to obtain the exact data that you want.

Remarks

Consider the following points when you work with filters:

By default, Windows Live Contacts returns all entities and all fields. For example, a filter that contains "LiveContacts" or "LiveContacts(*)" returns everything.
Filters are case sensitive, and must conform to the hierarchy that is defined in the overall schema.
All filter definitions must start from the root element (LiveContacts).
Parentheses are used to represent hierarchy. Parentheses are safer for use during HTTP transmission than brackets or other such characters.
The filter header can specify that the caller wants to use a predefined filter, or the filter header can specify a custom filter. Windows Live Contacts determines whether the filter header is a predefined filter by comparing the Filter parameter to the predefined filter names. If none of the predefined filter names match, Windows Live Contacts parses the custom filter to determine which fields are being requested.
Collection elements are not considered a hierarchy element. For example, "Contacts" is not a valid filter item.
A filter that contains "… Contact(*), …" is equivalent to "… Contact, …". This means that children elements that are under "Contact" are returned.
A filter that contains "… Contact() … " means that nothing under "Contact" is returned except for an empty "Contact" element.
If children elements are specified for a parent element, only the specified children elements are returned. All other sibling elements are filtered out. For example, a filter that contains "… Email(ID, Address) …" only returns the address and the ID of the e-mail item.
You cannot define an exclusive filter. For example, you cannot specify a result that returns all children under the "Contact" node except for "Location". Instead, you must explicitly list all those children under the "Contact" node that should be returned except for "Location".
If a filter is not valid or returns no data, Windows Live Contacts sends a "204 No Content" response header.

Examples

Description

The following example header uses a predefined filter to extract phone contact information:

Code

https://livecontacts.services.live.com/users/@L@<lid>/rest/livecontacts&Filter=Phone

Description

The following example header uses a custom filter to extract specific fields:

Code

https://livecontacts.services.live.com/users/@L@<lid>/rest/livecontacts&Filter=LiveContacts(Contact(ID,CID,WindowsLiveID,AutoUpdateEnabled,AutoUpdateStatus,Profiles,Email,Phone,Locations,URI),Tag)

Concepts

Getting Started with Windows Live Contacts API
About the Windows Live Contacts API
Using Windows Live Contacts API