Printer Friendly Version      Send     
Click to Rate and Give Feedback
MSDN
MSDN Library
Web Development
Windows Live
Address Book Schema
 REST Schema Details
Windows Live
Windows Live Contacts API: REST Schema Details

The following tables list all the valid elements for the Windows Live Contacts address book schema. Additionally, the tables list the minimum and maximum number of elements allowed and the access permissions for each element.

Element Min Occurrences Max Occurrences Create Update

<LiveContacts>

 

 

 

 

    <Owner>

1

1

  -

  -

        …

 

 

 

 

    </Owner>

 

 

 

 

    <Contacts>

0

1

  -

 -

        …

 

 

 

 

    </Contacts>

 

 

 

 

    <Tags>

0

1

 -

 -

        …

 

 

 

 

    </Tags>

 

 

 

 

</LiveContacts>

 

 

 

 

Element Max/Type Min Occurrences Max Occurrences Create Update

<Owner>

 

1

1

 -

 -

    <CID>UniqueID</CID>

64 bit decimal

1

1

RO

RO

    <WindowsLiveID>Windows Live ID</WindowsLiveID>

string

1

1

RO

RO

    <Profiles></Profiles>

Container

0

1

RO

RO

    <Emails></Emails>

Collection

0

1

RO

RO

    <Phones></Phones>

Collection

0

1

RO

RO

    <Locations></Locations>

Collection

0

1

RO

RO

    <URIs></URIs>

Collection

0

1

RO

RO

</Owner>

 

 

 

 

 

Details

  • CID: Unique ID for the Address Book owner.
  • WindowsLiveID: The Windows Live ID (e-mail address) for the Address Book Owner.
  • Profiles: Matching the Profile schema associated with Contacts, this contains information about the Owner as copied from their Windows Live Profile.
  • Emails: Matching the Email schema associated with Contacts, this contains information about the Owner as copied from their Windows Live Profile.
  • Phones: Matching the Phone schema associated with Contacts, this contains information about the Owner as copied from their Windows Live Profile.
  • Locations: Matching the Location schema associated with Contacts, this contains information about the Owner as copied from their Windows Live Profile.
  • Locations: Matching the URI schema associated with Contacts, this contains information about the Owner as copied from their Windows Live Profile.

Element Min Occurrences Max Occurrences Create Update

<Contacts>

0

1

 -

 -

    <Contact>

1

n

 -

 -

        …

 

 

 

 

    </Contact>

 

 

 

 

</Contacts>

 

 

 

 

Element Max/Type Min Occurrences Max Occurrences Create Update

<Contact>

 

1

n

 -

 -

    <ID>ContactID</ID>

guid

1

1

RO

RO

    <CID>UniqueID</CID>

64 bit decimal

1

1

RO

RO

    <WindowsLiveID>Windows Live ID</WindowsLiveID>

321 chars

0

1

RW

RW

    <AutoUpdateEnabled>TrueFalse</AutoUpdateEnabled>

boolean

0

1

RO

RO

    <AutoUpdateStatus>Status</AutoUpdateStatus>

enum

0

1

RO

RO

    <Profiles>

collection

 

 

 

 

        …

 

 

 

 

 

    </Profiles>

 

 

 

 

 

    <Emails>

collection

0

1

 -

 -

        …

 

 

 

 

 

    </Emails>

 

 

 

 

 

    <Phones>

collection

0

1

 -

 -

        …

 

 

 

 

 

    </Phones>

 

 

 

 

 

    <Locations>

collection

0

1

 -

 -

        …

 

 

 

 

 

    </Locations>

 

 

 

 

 

    <URIs>

collection

0

1

 -

 -

        …

 

 

 

 

 

    </URIs>

 

 

 

 

 

</Contact>

 

 

 

 

 

Details

  • ID: 128 Bit Decimal. Unique ID of the contact.within this address book
  • CID: Unique ID for the Contact.
  • WindowsLiveID: If the contact has a Windows Live ID which is known by the Address Book owner, it will be returned here. If supplied in a POST or PUT method call, it will be verified. If not a valid Windows Live ID, the method will fail.
  • AutoUpdateEnabled: Indicates if this contact's details are auto-updated by the contact's Windows Live profile. This value is Read-Only from the REST API. If Live or LivePending then True, otherwise False.
  • AutoUpdateStatus: If the value of AutoUpdateEnabled is equal to False, then this value is null, otherwise the value is set to LivePending or Live. This value is always Read Only. The value of Live means that the connection has been made and this contact record has received at least one update from the contact's profile. The value of LivePending means that this has been set as an auto-updating contact by the owner, but it has not yet received any updates from the contact's profile (which may be because they don't have one, or the Address Book owner doesn't have permission to subscribe to updates, or that the contact's profile subscription list is already full.
  • Profiles: Unique profile information on this contact.
  • Emails: Collection of Emails for this contact.
  • Phones: Collection of Phone Numbers for this contact.
  • Locations: Collection of Locations for this contact.
  • URIs: Collection of URIs associated with this contact.

Element Min Max Create Update

<Profiles>

 

 

 

 

    <Personal>

1

1

 -

 -

        …

 

 

 

 

    </Personal>

 

 

 

 

    <Professional>

0

1

 -

 -

        …

 

 

 

 

    </Professional>

 

 

 

 

</Profiles>

 

 

 

 

Element Max/Type Min Occurrences Max Occurrences Create Update

<Personal>

 

1

1

 -

 -

    <NameToFileAs>FileName</NameToFileAs>

40 chars

0

1

RW

RW

    <NameTitle>NameTitle</NameTitle>

40 chars

0

1

RW

RW

    <FirstName>FirstName</FirstName>

40 chars

0

1

RW

RW

    <MiddleName>MiddleName</MiddleName>

40 chars

0

1

RW

RW

    <LastName>LastName</LastName>

40 chars

0

1

RW

RW

    <Suffix>Suffix</Suffix>

40 chars

0

1

RW

RW

    <YomiFirstName>FirstNamePronunciation</YomiFirstName>

120 chars

0

1

RW

RW

    <YomiLastName>LastNamePronunciation</YomiLastName>

120 chars

0

1

RW

RW

    <UniqueName>unique name</UniqueName>

40 chars

1

1

RO

RO

    <SortName>sort name</SortName>

40 chars

1

1

RO

RO

    <NickName>nickname</NickName>

40 chars

1

1

RW

RW

    <DisplayName>display name</DisplayName>

40 chars

1

1

RO

RO

    <Birthdate>TimeStamp</Birthdate>

datetime

0

1

RW

RW

    <Anniversary>Date</Anniversary>

10 chars

0

1

RW

RW

    <Gender>Gender</Gender>

enum

0

1

RW

RW

    <TimeZone>TimeZone</TimeZone>

enum

0

1

RW

RW

    <SpouseName>SpouseName</SpouseName>

120 chars

0

1

RW

RW

</Personal>

 

 

 

 

 

Details

  • NameToFileAs: Name under which to file and sort this Contact (e.g. LastName+FirstName values etc.) See Outlook Contacts.
  • NameTitle: Prefix e.g. Mr., Dr., Mrs., etc.
  • FirstName: The contact's first name.
  • MiddleName: The contact's middle name.
  • LastName: The contact's last name.
  • Suffix: The contact's name suffix e.g. MP
  • YomiFirstName: Pronunciation Guide for Asian names. Nullable. The maximum length 120 characters. Excess characters will be silently truncated.
  • YomiLastName: Pronunciation Guide for Asian names. Nullable. Max Length 120 chars. Excess chars will be silently truncated.
  • UniqueName: Auto generated to help with deduplication processes.
  • SortName: Auto generated from available contact fields to help identify and sort Contacts by name.
  • NickName: Name entered by Address Book owner in Live Messenger client to override Contact's own preferred displayname.
  • DisplayName: Name entered by the Contact themselves as their preferred displayname.
  • Birthdate: See Windows Live Contacts API: Date Values, Range and Validation for more information.
  • Anniversary: A string field for the anniversary date rather than a true datetime field.
  • Gender: Valid values are:
    • Unspecified (default)
    • Male
    • Female
  • TimeZone: Valid values are:
    • None (default)
    • GmtMinus12h
    • GmtMinus11h
    • GmtMinus10h
    • GmtMinus9h
    • GmtMinus8h
    • GmtMinus7h
    • GmtMinus6h
    • GmtMinus5h
    • GmtMinus4h
    • GmtMinus3h30
    • GmtMinus3h
    • GmtMinus2h
    • GmtMinus1h
    • Gmt
    • GmtPlus1h
    • GmtPlus2h
    • GmtPlus3h
    • GmtPlus3h30
    • GmtPlus4h
    • GmtPlus4h30
    • GmtPlus5h
    • GmtPlus5h30
    • GmtPlus5h45
    • GmtPlus6h
    • GmtPlus6h30
    • GmtPlus7h
    • GmtPlus8h
    • GmtPlus9h
    • GmtPlus9h30
    • GmtPlus10h
    • GmtPlus11h
    • GmtPlus11h30
    • GmtPlus12h
    • GmtPlus13h
  • SpouseName: Full Name of the contact's Spouse.

Element Max/Type Min Occurrences Max Occurrences Create Update

<Professional>

 

0

1

 -

 -

    <JobTitle>JobTitle</JobTitle>

120 chars

0

1

RW

RW

    <Profession>Profession</Profession>

120 chars

0

1

RW

RW

    <Manager>ManagerName</Manager>

120 chars

0

1

RW

RW

    <Assistant>AssistantName</Assistant>

120 chars

0

1

RW

RW

</Professional>

 

 

 

 

 

Details

  • JobTitle: Job title of the contact.
  • Profession: The contact's profession e.g. doctor.
  • Manager: The contact's Manager's name.
  • Assistant: The contact's Assistant's name.

Element Min Max Create Update

<Emails>

0

1

 -

 -

    <Email>

0

n

 -

 -

        …

 

 

 

 

    </Email>

 

 

 

 

</Emails>

 

 

 

 

Element Max/Type Min Occurrences Max Occurrences Create Update

<Email>

 

0

n

 -

 -

    <ID>EmailID</ID>

guid

1

1

RO

RO

    <EmailType>WindowsLiveID</EmailType>

enum

1

1

RW

RO

    <Address>someone@example.com</Address>

321 chars

1

1

RW

RW

    <IsIMEnabled>TrueFalse</IsIMEnabled>

boolean

1

1

RO

RO

    <IsDefault>TrueFalse</IsDefault>

boolean

1

1

RW

RW

</Email>

 

 

 

 

 

Details

  • ID: Initially linked to the EmailType, this is the unique identifier for the Email record associated with this contact. It cannot be updated.
  • EmailType: Once created, the EmailType of an existing Email record cannot be changed. If an e-mail address changes type, then a new record would need to be created and the existing one deleted. It is not possible to create more than one instance of the same EmailType associated with one contact. Valid values are:
    • WindowsLiveID
    • Personal
    • Business
    • Other
  • Address: If this contact was created through a subscription or friend mechanism without knowing the Windows Live ID, the contact may be linked to a Windows Live profile or space, but the Windows Live ID will not be available to the address book owner until explicitly set through the API with a POST method call. If the Windows Live ID EmailType is used, then this Address value is checked to ensure it is a valid Windows Live ID. Any other EmailType Address value is validated for conformity with the e-mail format. This value must be a valid SMTP address. The validation was jointly defined with Hotmail and matches Hotmail's validation criteria. The validation will fail if any of the following conditions are true:
    • there is no @ sign,
    • @ is the first character,
    • @ is the last character,
    • there is no dot after the @,
    • a dot is the last character,
    • a space exists within the string,
    • a comma exists anywhere in the string,
    • there is more than one @.
  • IsIMEnabled: If this e-mail address is set up in the service to allow Messenger Communication, this value is set to the value of True.
  • IsDefault: If the internal PrimaryEmailType equals this EmailType then this flag is set to the True value, otherwise the default value of False is used until set otherwise by the caller.

If the Windows Live ID EmailType is removed on an auto-updating contact, then the contact will no longer receive updates and that flag will be set to the value of False.

If the Address of the Windows Live ID EmailType is updated, then the IsIMEnabled flag will be set to the value of False automatically.

Element Min Max Create Update

<Phones>

0

1

 -

 -

    <Phone>

0

n

 -

 -

        …

 

 

 

 

    </Phone>

 

 

 

 

</Phones>

 

 

 

 

Element Max/Type Min Occurrences Max Occurrences Create Update

<Phone>

 

0

n

 -

 -

    <ID>PhoneID</ID>

guid

1

1

RO

RO

    <PhoneType>PhoneType</PhoneType>

enum

1

1

RW

RO

    <Number>PhoneNumber</Number>

50 chars

1

1

RW

RW

    <IsIMEnabled>TrueFalse</IsIMEnabled>

boolean

1

1

RO

RO

    <IsDefault>TrueFalse</IsDefault>

boolean

1

1

RW

RW

</Phone>

 

 

 

 

 

Details

  • ID: Initially linked to the PhoneType, this is the unique identifier for the Phone record associated with this contact. It cannot be updated.
  • PhoneType: Once created, the PhoneType of an existing Phone record cannot be changed. If a phone number changes type, then a new record would need to be created and the existing one deleted. It is not possible to create more than one instance of the same PhoneType associated with one contact. Valid values are:
    • Personal
    • Business
    • Mobile
    • Pager
    • Fax
    • Other
    • Personal2
    • Business2
    • BusinessFax
    • Company
    • Assistant
    • Callback
    • Car
    • ISDN
    • OtherFax
    • Primary
    • Radio
    • Telex
    • TTY
    • MSN
    • IP
    • BusinessMobile
  • Number: To allow for possible Messenger usage, it is best that these numbers are fully qualified URIs, i.e., including the country code prefixed by a + sign. However, this is not enforced by the service. This value is stored as ANSI code, not as Unicode. If Unicode is passed, .NET converts from Unicode to ANSI using the ANSI codepage and any DBCS characters will get translated to the '?' character.
  • IsIMEnabled: If this phone number is set up in the service to allow Messenger Communication, this value is set to the value of True. If the phone number is updated for which the IsIMEnabled is currently set to the value of True, then this will be set to the value of False automatically.
  • IsDefault: If the internal PrimaryPhoneType equals this PhoneType then this flag is set to the value of True, otherwise the default value is set to False until set otherwise by the caller.

Element Min Max Create Update

<Locations>

0

1

 -

 -

    <Location>

0

n

 -

 -

        …

 

 

 

 

    </Location>

 

 

 

 

</Locations>

 

 

 

 

Element Max/Type Min Occurrences Max Occurrences Create Update

<Location>

 

0

n

 -

 -

    <ID>LocationID</ID>

guid

1

1

RO

RO

    <LocationType>LocationType</LocationType>

Enum

1

1

RW

RO

    <Office>OfficeName</Office>

40 chars

0

1

RW

RW

    <Department>DepartmentName</Department>

40 chars

0

1

RW

RW

    <CompanyName>CompanyName</CompanyName>

40 chars

0

1

RW

RW

    <YomiCompanyName>YomiCompanyName</YomiCompanyName>

100 chars

0

1

RW

RW

    <StreetLine>StreetNameLine1</StreetLine>

256 chars

0

1

RW

RW

    <StreetLine2>StreetNameLine2</StreetLine2>

256 chars

0

1

RW

RW

    <PrimaryCity>CityLine1</PrimaryCity>

40 chars

0

1

RW

RW

    <SecondaryCity>CityLine2</SecondaryCity>

40 chars

0

1

RW

RW

    <SubDivision>StateOrProvince</SubDivision>

40 chars

0

1

RW

RW

    <PostalCode>PostcodeOrZipcode</PostalCode>

40 chars

0

1

RW

RW

    <CountryRegion>Country</CountryRegion>

40

0

1

RW

RW

    <Latitude>Latitude</Latitude>

decimal(7.4)

0

1

RW

RW

    <Longitude>Longitude</Longitude>

decimal(7.4)

0

1

RW

RW

    <IsDefault>TrueFalse</IsDefault>

boolean

1

1

RW

RW

</Location>

 

 

 

 

 

Details

  • ID: Initially linked to the LocationType, this is the unique identifier for the Location record associated with this contact. It cannot be updated.
  • LocationType: Once created, the LocationType of an existing Location record cannot be changed. If a phone number changes type, then a new record would need to be created and the existing one deleted. It is not possible to create more than one instance of the same LocationType associated with one contact. Valid values are:
    • Personal
    • Business
    • Other
  • Office: Although not validated by the service, this is usually only used with the Business LocationType.
  • Department: Although not validated by the service, this is usually only used with the Business LocationType.
  • CompanyName: Although not validated by the service, this is usually only used with the Business LocationType.
  • YomiCompanyName: Although not validated by the service, this is usually only used with the Business LocationType. Pronunciation Guide for Asian names. Nullable. The maximum length 120 characters. Excess characters will be silently truncated.
  • StreetLine: See http://msdn2.microsoft.com/en-us/library/aa502351.aspx for more information on the recommended usage of the address fields.
  • StreetLine2: See http://msdn2.microsoft.com/en-us/library/aa502351.aspx for more information on the recommended usage of the address fields.
  • PrimaryCity: See http://msdn2.microsoft.com/en-us/library/aa502351.aspx for more information on the recommended usage of the address fields.
  • SecondaryCity: See http://msdn2.microsoft.com/en-us/library/aa502351.aspx for more information on the recommended usage of the address fields.
  • SubDivision: See http://msdn2.microsoft.com/en-us/library/aa502351.aspx for more information on the recommended usage of the address fields.
  • PostalCode: See http://msdn2.microsoft.com/en-us/library/aa502351.aspx for more information on the recommended usage of the address fields.
  • CountryRegion: See http://msdn2.microsoft.com/en-us/library/aa502351.aspx for more information on the recommended usage of the address fields.
  • Latitude: The latitude in degrees of this location. This can be any value between and including -90.0 to +90.0. If the street or city values of the location attributes are changed without also setting the Latitude and Longitude values, then any existing Latitude or Longitude values currently stored against that address will be cleared.
  • Longitude: The longitude in degrees of this location. This can be any value between and including -180.0 to +180.0. If the street or city values of the location attributes are changed without also setting the Latitude and Longitude values, then any existing Latitude or Longitude values currently stored against that address will be cleared.
  • IsDefault: If the internal PrimaryLocationType equals this LocationType then this flag is set to the value of True, otherwise the default value is set to False until set otherwise by the caller.

Element Min Max Create Update

<URIs>

0

1

 -

 -

    <URI>

0

n

 -

 -

        …

 

 

 

 

    </URI>

 

 

 

 

</URIs>

 

 

 

 

Element Max/Type Min Occurrences Max Occurrences Create Update

<URI>

 

0

n

 -

 -

    <ID>URLID</ID>

integer

1

1

RO

RO

    <URIType>URIType</URIType>

enum

1

1

RW

RW

    <Name>URIName</Name>

128 chars

0

1

RW

RW

    <Address>URL</Address>

2048 chars

1

1

RW

RW

</URI>

 

 

 

 

 

Details

  • ID: This is the unique identifier for the URL record associated with this contact. It cannot be updated.
  • URIType: An enum indicating the type of URL being stored. There is a fixed list of standard types which are shown in the URLType Usage table, below. This does not have to be unique across the contact, so may be as many of the same type as needed and that can be created e.g. more than one Attachment record could be associated with this contact.
  • Name: For most types, the Name value is not needed, but if the URLType value of Other is chosen, then it is expected that the calling application would either hard-code a URLName value or allow the user to enter one e.g. this contact's "Music Site".
  • Address: This value is stored Unicode (nvarchar).

URIType Usage Description

Image

This will be used for URLs referring to the storage location of the Contact Tile previously uploaded by the client application.

Attachment

This will be used for URLs referring to the storage location of individual attachments previously uploaded by the client application.

EBCDisplayDefinition

This will be used for URLs referring to the storage location of the Electronic Business Card Display Definition previously uploaded by the client application.

EBCLogo

This will be used for URLs referring to the Storage location of the Electronic Business Card Logo previously uploaded by the client application.

EBCFinalImage

This will be used for URLs referring to the Storage location of the Electronic Business Card Final Image previously uploaded by the client application.

Feed

Used to indicate that this URL points to an RSS or PodCast type feed.

Other

This will be used for any URL type not already in this list, but then described in the URLName field, allowing applications to extend this list.

Element Min Max Create Update

<Tags>

0

1

 -

 -

    <Tag>

1

n

 -

 -

        …

 

 

 

 

    </Tag>

 

 

 

 

</Tags>

 

 

 

 

Element Max/Type Min Occurrences Max Occurrences Create Update

<Tag>

 

 

 

 

 

    <ID>GroupID|CategoryID</ID>

guid

1

1

RO

RO

    <Name>TagName</Name>

40 chars

1

1

RW

RW

    <ContactIDs>

collection

0

1

 -

 -

        <ContactID><ID>…</ID></ContactID>

 

 

 

 

 

    </ContactIDs>

 

 

 

 

 

</Tag>

 

 

 

 

 

Details

  • ID: This is the unique identifier for the Tag record associated with this address book. It cannot be updated.
  • Name: Contacts can be associated with zero or any number of Tag collections. The tag types that appear in Windows Live Messenger and Windows Live Hotmail are a special type of tag and have a prefix of "MSGR:" in this schema. They appear as groups of contacts in Messenger and Hotmail (the prefix is not displayed in those applications). Messenger and Hotmail tags (groups) can be created with a "MSGR:" prefix e.g. "MSGR:Family", but cannot be updated to remove the "MSGR:" prefix once created in this way. Non Messenger and Hotmail tags can have alternative prefixes or no prefix, but cannot be updated to add a "MSGR:" prefix later. These tags will not appear in Messenger or Hotmail so can safely be used to produce alternative views or groups. Messenger and Hotmail tags have 60 characters available for the name. All other tags have 40 characters available.

Element Min Max Create Update

<ContactIDs>

0

1

 -

 -

    <ContactID>ContactID</ContactID>

1

n

RW

RO

</ContactIDs>

 

 

 

 

Details

  • ContactID: 128 Bit Decimal. Unique ID of the contact belonging to this group. ContactID elements may only be inserted or deleted. They cannot be individually updated.

The following abbreviations are used in the previous tables:

  • Min: Represents the minimum number of elements that can be defined for a particular element.
  • Max: Represents the maximum number of elements that can be defined for a particular element.
  • n : Indicates that the maximum number of elements is limited only by the available quota for that container if a quota is set, otherwise the maximum number of elements is limited by the number of available Types.
  • RW: Represents read and write access.
  • RO: Represents read-only access.
  • Placeholders are indicated as follows: PlaceHolder, where PlaceHolder represents the name of the placeholder.
© 2008 Microsoft Corporation. All rights reserved. Terms of Use  |  Trademarks  |  Privacy Statement
Page view tracker