GetImItems operation

Find information about the GetImItems EWS operation.

The GetImItems operation retrieves information about instant messaging (IM) groups and IM contact personas.

This operation was introduced in Exchange Server 2013.

Using the GetImItems operation

The GetImItems operation accepts group and contact item identifiers and returns a set of information about the groups and contacts. The property sets returned in the response are identified by extended properties, multiple contact identifiers, group identifiers, and extended property definitions as arguments.

GetImItems operation SOAP headers

The GetImItems operation can use the SOAP headers that are listed in the following table.

Header name	Element	Description
Impersonation	ExchangeImpersonation	Identifies the user whom the client application is impersonating. This header is applicable to a request.
MailboxCulture	MailboxCulture	Identifies the culture, as defined in RFC 3066, "Tags for the Identification of Languages", to be used to access the mailbox. This header is applicable to a request.
RequestVersion	RequestServerVersion	Identifies the schema version for the operation request. This header is applicable to a request.
ServerVersion	ServerVersionInfo	Identifies the version of the server that responded to the request. This header is applicable to a response.

GetImItems operation request example: Get detailed information about IM contacts and groups

The following example of a GetImItems operation request shows how to request detailed information about IM contacts and groups. A GetImItems operation can request one or more contact or group details. You can also use extended properties to get custom properties on groups and contacts. If a requested extended property does not exist on an item, the response will ignore the requested property and return the response for the default property set. This example shows you how to get the display name by using extended properties.

Note

All item identifiers and change keys in this article have been shortened to preserve readability. Note that change keys are ignored by the service for this operation.

<?xml version="1.0" encoding="UTF-8"?>
<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/"
               xmlns:t="http://schemas.microsoft.com/exchange/services/2006/types"
               xmlns:m="http://schemas.microsoft.com/exchange/services/2006/messages">
   <soap:Header>
      <t:RequestServerVersion Version="Exchange2013" />
      <t:MailboxCulture>en-US</t:MailboxCulture>
   </soap:Header>
   <soap:Body >
      <m:GetImItems>
         <m:ContactIds>
            <t:ItemId Id="AAMkADEzOTExYACABmEhpSAAA=" ChangeKey="EQAAABBmNDjF"/>
         </m:ContactIds>
         <m:GroupIds>
            <t:ItemId Id="AAMkADEzOTExYjJkBY7+0EAAA=" ChangeKey="EgAAAA=="/>
         </m:GroupIds>         
         <m:ExtendedProperties>
            <t:ExtendedProperty PropertyTag="0x3001" PropertyType="String"/>
         </m:ExtendedProperties>
      </m:GetImItems>
   </soap:Body>
</soap:Envelope>

The request SOAP body contains the following elements:

• GetImItems

• ContactIds

• ItemId

• GroupIds

• ExtendedProperties (NonEmptyArrayOfExtendedFieldURIs)

• ExtendedProperty (PathToExtendedFieldType)

Successful GetImItems operation response

The following example shows a successful response to a GetImItems request to get an IM contact and group. The display name is requested in an extended property. IM contacts are returned in the form of a persona.

<?xml version="1.0" encoding="utf-8"?>
<s:Envelope xmlns:s="http://schemas.xmlsoap.org/soap/envelope/">
   <s:Header>
      <h:ServerVersionInfo MajorVersion="15" 
                           MinorVersion="0" 
                           MajorBuildNumber="556" 
                           MinorBuildNumber="8" 
                           Version="Exchange2013" 
                           xmlns:h="http://schemas.microsoft.com/exchange/services/2006/types" 
                           xmlns="http://schemas.microsoft.com/exchange/services/2006/types" 
                           xmlns:xsd="http://www.w3.org/2001/XMLSchema" 
                           xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"/>
   </s:Header>
   <s:Body xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
           xmlns:xsd="http://www.w3.org/2001/XMLSchema">
      <GetImItemsResponse ResponseClass="Success" 
                          xmlns="http://schemas.microsoft.com/exchange/services/2006/messages">
         <ResponseCode>NoError</ResponseCode>
         <ImItemList>
            <Groups xmlns="http://schemas.microsoft.com/exchange/services/2006/types">
               <ImGroup>
                  <DisplayName>Exchange SDK Team</DisplayName>
                  <GroupType>IPM.DistList.MOC.UserGroup</GroupType>
                  <ExchangeStoreId Id="AAMkADEzQrAABY7+0EAAA=" ChangeKey="EgAAAA=="/>
                  <MemberCorrelationKey>
                     <ItemId Id="AAMkADEzOTExYjeGgGqm4QrAABmEhpSAAA=" ChangeKey="EQAAAA=="/>
                  </MemberCorrelationKey>
                  <ExtendedProperties>
                     <ExtendedProperty>
                        <ExtendedFieldURI PropertyTag="0x3001" PropertyType="String"/>
                        <Value>Exchange SDK Team</Value>
                     </ExtendedProperty>
                  </ExtendedProperties>
               </ImGroup>
            </Groups>
            <Personas xmlns="http://schemas.microsoft.com/exchange/services/2006/types">
               <Persona>
                  <PersonaId Id="AAQkADEzOTBZImBzN5J/uHXc="/>
                  <PersonaType>Person</PersonaType>
                  <CreationTime>2012-11-07T00:10:35Z</CreationTime>
                  <DisplayName>Tony Smith</DisplayName>
                  <DisplayNameFirstLast>Tony Smith</DisplayNameFirstLast>
                  <DisplayNameLastFirst>Tony Smith</DisplayNameLastFirst>
                  <FileAs/>
                  <FileAsId>None</FileAsId>
                  <ImAddress>tsmith@contoso.com</ImAddress>
                  <RelevanceScore>2147483647</RelevanceScore>
                  <Attributions>
                     <Attribution>
                        <Id>0</Id>
                        <SourceId Id="AAMkADEzhQaoeGgGqm4QrAABmEhpSAAA=" ChangeKey="EQArAABmNDjF"/>
                        <DisplayName>Lync Contacts</DisplayName>
                        <IsWritable>false</IsWritable>
                        <IsQuickContact>true</IsQuickContact>
                        <IsHidden>false</IsHidden>
                     </Attribution>
                  </Attributions>
                  <DisplayNames>
                     <StringAttributedValue>
                        <Value>Tony Smith</Value>
                        <Attributions>
                           <Attribution>0</Attribution>
                        </Attributions>
                     </StringAttributedValue>
                  </DisplayNames>
                  <FileAsIds>
                     <StringAttributedValue>
                        <Value>None</Value>
                        <Attributions>
                           <Attribution>0</Attribution>
                        </Attributions>
                     </StringAttributedValue>
                  </FileAsIds>
                  <ImAddresses>
                     <StringAttributedValue>
                        <Value>tsmith@contoso.com</Value>
                        <Attributions>
                           <Attribution>0</Attribution>
                        </Attributions>
                     </StringAttributedValue>
                  </ImAddresses>
                  <ExtendedProperties>
                     <ExtendedPropertyAttributedValue>
                        <Value>
                           <ExtendedFieldURI PropertyTag="0x3001" PropertyType="String"/>
                           <Value>Tony Smith</Value>
                        </Value>
                        <Attributions>
                           <Attribution>0</Attribution>
                        </Attributions>
                     </ExtendedPropertyAttributedValue>
                  </ExtendedProperties>
               </Persona>
            </Personas>
         </ImItemList>
      </GetImItemsResponse>
   </s:Body>
</s:Envelope>

The response SOAP body contains the following elements:

• GetImItemsResponse

• ResponseCode

• ImItemList

• Groups (ArrayOfImGroupType)

• ImGroup

• DisplayName (string)

• GroupType

• ExchangeStoreId

• MemberCorrelationKey

• ItemId

• ExtendedProperties (NonEmptyArrayOfExtendedFieldURIs)

• ExtendedProperty (PathToExtendedFieldType)

• Personas

• PersonaId

• PersonaType

• CreationTime

• DisplayNameFirstLast

• DisplayNameLastFirst

• FileAs

• FileAsId FileAsId

• ImAddress (String)

• RelevanceScore

• Attributions (ArrayOfPersonaAttributionsType)

• Attribution (PersonaAttributionType)

• ID (String)

• SourceId

• IsWritable

• IsQuickContact

• IsHidden

• StringAttributedValue

• FileAsIds

• ImAddresses

• Value (ExtendedPropertyType)

GetImItems operation error response

The GetImItems operation does not validate identifiers and will not return the expected ErrorInvalidImContactId or ErrorInvalidImGroupId error response if an invalid contact or group identifier is provided to the service.

See also

• EWS operations in Exchange

• GetImItemList operation