# Table of contents:

• Introduction
• Authentication
  • Using Cookies
  • Using SOAP
• Actions
  • Actions that we don't know much about
• Shared Templates
  • Client/Request
    • soap:Envelope
      • soap:Header
        • ABApplicationHeader
        • ABAuthHeader
      • soap:Body
  • Server/Response
    • soap:Envelope
      • soap:Header
        • ServiceHeader
      • soap:Body

# Introduction

The Address Book Service (abservice), also known as the Address Book Clearing House (ABCH) is a SOAP (XML) Web Service. It was introduced with MSNP8.

It manages the entries on both the e-mail service's address book and the unified Forward List (FL) that was introduced in MSNP13.

It's default HTTP URL is http://contacts.msn.com/abservice/abservice.asmx.
It's default HTTPS URL is https://contacts.msn.com/abservice/abservice.asmx.

Related: Contact Sharing Service (for other List's members).

# Authentication

This service requires Passport Authentication, either using Passport SSI 1.4, Passport Request Security Token service or the Passport Request Security Token service, version 2.

There are two ways to authenticate.

# Using Cookies

The easiest way to authenticate is by setting the MSPAuth cookie to the MSPAuth value from your Passport Compact Token (everything after t= and before &p=)

This can be done using a token for either contacts.msn.com or messenger.msn.com.

# Using SOAP

Starting with Official Client 8.1.0064, the Official Client will use SOAP to authenticate with the service. See the ABAuthHeader section for more information.

This method of authentication only works with a token for contacts.msn.com.

# Actions

All actions listed have the prefix of http://www.msn.com/webservices/AddressBook/.

• ABFind (internal name: Contacts.FindId)
• ABAdd (internal name: Contacts.AddAb)
• ABDelete (internal name: Contacts.DeleteAb)
• ABUpdate
• ABFindAll (internal name: Contacts.Pull)
• ABContactAdd (internal name: Contacts.Push.Contact.Add)
• ABContactDelete (internal name: Contacts.Push.Contact.Delete)
• ABContactUpdate (internal name: Contacts.Push.Contact.Update)
• ABGroupContactAdd (internal name: Contacts.Push.Contact.AddToGroup)
• ABGroupContactDelete (internal name: Contacts.Push.Contact.DeleteFromGroup)
• ABGroupAdd (internal name: Contacts.Push.Group)
• ABGroupDelete (internal name: Contacts.Push.Group.Delete)
• ABGroupUpdate (internal name: Contacts.Push.Contact.Edit)
• AddDynamicItem (internal name: Contacts.Push.DynamicItem.Add)
• UpdateDynamicItem (internal name: Contacts.Push.DynamicItem.Edit)

# Actions that we don't know much about

• ABContactFind
• ABFindByContacts (internal name: Contacts.Pull.Id)
• ABFindByGroups
• ABFindMessengerUsers
• ABFindMeContact
• ABGroupFind
• ABAllowListGet
• ABAllowListSet

# Shared Templates

This is used by all Actions listed, as far as we know. The following also applies to the Contact Sharing Service.

# Client/Request

The following sub-headings are XML elements for the client's request.

# soap:Envelope

This element has three attributes:

• xmlns:soap: This is always set to http://schemas.xmlsoap.org/soap/envelope/.
• xmlns:xsi: This is always set to http://www.w3.org/2001/XMLSchema-instance.
• xmlns:xsd: This is always set to http://www.w3.org/2001/XMLSchema.

There may be one optional attribute:

• xmlns:soapenc: This is always set to http://schemas.xmlsoap.org/soap/encoding/. (This usually shows up if the client is using version 8 or higher of the Official Client.)

# soap:Header

This element only serves to host the <ABApplicationHeader> and <ABAuthHeader> elements.

# ABApplicationHeader

This element has only one attribute:

• xmlns: This is always set to http://www.msn.com/webservices/AddressBook.

This element has three children:

• <ApplicationID>: The GUID of the client that sent the request for this action.
• <IsMigration>: If this request is part of the ABCH Migration process. If it is, set to true, otherwise set to false.
• <PartnerScenario>: What caused this request to happen:
  • Initial: This is the initial request to this action.
  • Timer: This request was done automatically on a timer.
  • ContactSave: When the modified contact is saved by the client.
  • MessengerPendingList: Managing the Pending List (PL).
  • ContactMsgrAPI: General Messenger API.
  • BlockUnblock: Block or unblock of this user.
  • GroupSave: When the modified group is saved by the client.
  • RoamingIdentityChanged: The user's identity was modified.

# ABAuthHeader

This element has only one attribute:

• xmlns: This is always set to http://www.msn.com/webservices/AddressBook.

This element has two children:

• <ManagedGroupRequest>: If this is a managed group request, set to true, otherwise set to false.
• <TicketToken> This element contains the XML-encoded Passport Compact token for contacts.msn.com (see above). Added since MSNP15.

# soap:Body

Your request element and it's children goes here.

# Server/Response

The following sub-headings are XML elements for the server's response.

# soap:Envelope

This element has three attributes:

• xmlns:soap: This is always set to http://schemas.xmlsoap.org/soap/envelope/.
• xmlns:xsi: This is always set to http://www.w3.org/2001/XMLSchema-instance.
• xmlns:xsd: This is always set to http://www.w3.org/2001/XMLSchema.

# soap:Header

This element only serves to host the <ServiceHeader> element.

# ServiceHeader

This element has only one attribute:

• xmlns: This is always set to http://www.msn.com/webservices/AddressBook.

This element has five children:

• <Version>: The version of this service.
• <CacheKey>: The current or new address book caching key. Usually starts with 14r2;, then continues with base64-encoded data. The meaning of the appended data is yet to be known. It may be a 128-bit hash of some kind.
• <CacheKeyChanged>: Did the <CacheKey> change? If it did, set to true, otherwise set to false.
• <PreferredHostName>: The domain name that this service would like to receive requests to.
• <SessionId>: The current session GUID.

# soap:Body

This element contains the server's response elements and their children for the action.