Share via

[DEPRECATED] Outlook Contacts REST API reference (version 2.0)

  • Article

Applies to: Exchange Online | Office 365 | Hotmail.com | Live.com | MSN.com | Outlook.com | Passport.com

Note

Version 2.0 of the Outlook REST API is deprecated.

As announced on November 17, 2020, version 2.0 of the Outlook REST API has been deprecated. The v2.0 REST endpoint will be fully decommissioned in March 2024, and the v2.0 documentation will be removed shortly afterwards. Migrate existing apps to use Microsoft Graph. See a comparison to start your migration.

The Outlook Contacts API provides access to a user's contacts and contact folders secured by Azure Active Directory on Office 365, and to similar data in Microsoft accounts specifically in these domains: Hotmail.com, Live.com, MSN.com, Outlook.com, and Passport.com.

Note

For simplicity of reference, the rest of this article uses Outlook.com to include these Microsoft account domains.

Not interested in v2.0 of the API? In the table of contents on the left, go to the Office 365 REST API reference section and select the version you want.

All Contacts API operations

Contact operations

Contacts are stored in contact folders. You can get, create, change, and delete contacts.

Contact folder operations

Contact folders can contain contacts and other contact folders. You can get contact folders and create contacts in a contact folder.

Contact photo operations

Each contact can have an optional contact picture. You can get or set a photo for a contact.

See also

Using the Contacts REST API

Authentication

Like other Outlook REST API, for every request to the Contacts API, you should include a valid access token. Getting an access token requires you to have registered and identified your app, and obtained the appropriate authorization.

You can find out more about some streamlined registration and authorization options for you. Keep this in mind as you proceed with the specific operations in the Contacts API.

Version of API

The Contacts REST API is supported in all versions of the Outlook REST API. The functionality may differ depending on the specific version.

Target user

The Contacts API requests are always performed on behalf of the current user.

See Use the Outlook REST API for more information common to all subsets of the Outlook REST API.

Get contacts

You can get a contact collection or an individual contact from a contact folder.

Minimum required scope

One of the following:

Get a contact collection

Get a contact collection from the default Contacts folder of the signed-in user (.../me/contacts), or from the specified contact folder.

GET https://outlook.office.com/api/v2.0/me/contacts
GET https://outlook.office.com/api/v2.0/me/contactfolders/{contact_folder_id}/contacts
Required parameter Type Description
URL parameters
contact_folder_id string The contact folder ID, if you're getting contacts from a specific folder.

Note

By default, each contact in the response includes all its properties. Use $select to specify only those properties you need for best performance. The Id property is always returned. See OData query parameters for filtering, sorting, and paging parameters.

Sample request

GET https://outlook.office.com/api/v2.0/me/contacts?$select=EmailAddresses,GivenName,Surname

Sample response

Status code: 200

{
    "@odata.context": "https://outlook.office.com/api/v2.0/$metadata#Me/Contacts(EmailAddresses,GivenName,Surname)",
    "value": [
        {
            "@odata.id": "https://outlook.office.com/api/v2.0/Users('ddfcd489-628b-40d7-b48b-57002df800e5@1717622f-1d94-4d0c-9d74-709fad664b77')/Contacts('AAMkAGI2THk3AAA=')",
            "@odata.etag": "W/\"EQAAABYAAACd9nJ/tVysQos2hTfspaWRAAADTIa7\"",
            "Id": "AAMkAGI2THk3AAA=",
            "GivenName": "Rob",
            "Surname": "Young",
            "EmailAddresses": [
                {
                    "Name": "roby@a830edad9050849NDA1.onmicrosoft.com",
                    "Address": "roby@a830edad9050849NDA1.onmicrosoft.com"
                }
            ]
        },
        {
            "@odata.id": "https://outlook.office.com/api/v2.0/Users('ddfcd489-628b-40d7-b48b-57002df800e5@1717622f-1d94-4d0c-9d74-709fad664b77')/Contacts('AAMkAGI2THkzAAA=')",
            "@odata.etag": "W/\"EQAAABYAAACd9nJ/tVysQos2hTfspaWRAAADTIa3\"",
            "Id": "AAMkAGI2THkzAAA=",
            "GivenName": "Janet",
            "Surname": "Schorr",
            "EmailAddresses": [
                {
                    "Name": "janets@a830edad9050849NDA1.onmicrosoft.com",
                    "Address": "janets@a830edad9050849NDA1.onmicrosoft.com"
                }
            ]
        }
    ]
}

Response type

The requested contact collection.

Get a contact

Minimum required scope

One of the following:

Get a contact by using the contact ID.

GET https://outlook.office.com/api/v2.0/me/contacts/{contact_id}
Required parameter Type Description
URL parameters
contact_id string The contact ID.

Sample request

GET https://outlook.office.com/api/v2.0/me/contacts/AAMkAGI2THk0AAA=

Sample response

Status code: 200

{
    "@odata.context": "https://outlook.office.com/api/v2.0/$metadata#Me/Contacts/$entity",
    "@odata.id": "https://outlook.office.com/api/v2.0/Users('ddfcd489-628b-40d7-b48b-57002df800e5@1717622f-1d94-4d0c-9d74-709fad664b77')/Contacts('AAMkAGI2THk0AAA=')",
    "@odata.etag": "W/\"EQAAABYAAACd9nJ/tVysQos2hTfspaWRAAADTIa4\"",
    "Id": "AAMkAGI2THk0AAA=",
    "CreatedDateTime": "2014-10-19T23:08:24Z",
    "LastModifiedDateTime": "2014-10-19T23:08:24Z",
    "ChangeKey": "EQAAABYAAACd9nJ/tVysQos2hTfspaWRAAADTIa4",
    "Categories": [],
    "ParentFolderId": "AAMkAGI2AAEOAAA=",
    "Birthday": null,
    "FileAs": "Fort, Garth",
    "DisplayName": "Garth Fort",
    "GivenName": "Garth",
    "Initials": "G.F.",
    "MiddleName": null,
    "NickName": "Garth",
    "Surname": "Fort",
    "Title": null,
    "YomiGivenName": null,
    "YomiSurname": null,
    "YomiCompanyName": null,
    "Generation": null,
    "EmailAddresses": [
        {
            "Name": "Garth",
            "Address": "garthf@a830edad9050849NDA1.onmicrosoft.com"
        }
    ],
    "ImAddresses": [
        "sip:garthf@a830edad9050849nda1.onmicrosoft.com"
    ],
    "JobTitle": "Web Marketing Manager",
    "CompanyName": "Contoso, Inc.",
    "Department": "Sales & Marketing",
    "OfficeLocation": "20/1101",
    "Profession": null,
    "BusinessHomePage": "https://www.contoso.com",
    "AssistantName": null,
    "Manager": null,
    "HomePhones": [],
    "MobilePhone1": null,
    "BusinessPhones": [
        "+1 918 555 0101"
    ],
    "HomeAddress": {},
    "BusinessAddress": {
      "Street": "10 Contoso Way",
      "City": "Redmond",
      "State": "WA",
      "CountryOrRegion": "USA",
      "PostalCode": "98075"
    },
    "OtherAddress": {},
    "SpouseName": null,
    "PersonalNotes": null,
    "Children": []
}

Response type

The requested contact.

Note

By default, the response includes all the properties of the contact. Use $select to specify only those properties you need for best performance. The Id property is always returned. See OData query parameters for filtering, sorting, and paging parameters.

The following example shows how to use $select to specify returning only the EmailAddresses, GivenName and Surname properties of the contact in the response.

Sample request

GET https://outlook.office.com/api/v2.0/me/contacts/AAMkAGI2THk0AAA=?$select=EmailAddresses,GivenName,Surname

Sample response

Status code: 200

{
    "@odata.context": "https://outlook.office.com/api/v2.0/$metadata#Me/Contacts(EmailAddresses,GivenName,Surname)/$entity",
    "@odata.id": "https://outlook.office.com/api/v2.0/Users('ddfcd489-628b-40d7-b48b-57002df800e5@1717622f-1d94-4d0c-9d74-709fad664b77')/Contacts('AAMkAGI2THk0AAA=')",
    "@odata.etag": "W/\"EQAAABYAAACd9nJ/tVysQos2hTfspaWRAAADTIa4\"",
    "Id": "AAMkAGI2THk0AAA=",
    "GivenName": "Garth",
    "Surname": "Fort",
    "EmailAddresses": [
        {
            "Name": "garthf@a830edad9050849NDA1.onmicrosoft.com",
            "Address": "garthf@a830edad9050849NDA1.onmicrosoft.com"
        }
    ]
}

Synchronize contacts and contact folders

You can synchronize your local list of contacts with the contacts on the server. Contacts synchronization is a per-folder operation, for example you can synchronize all of the contacts in your root Contacts folder. If you have additonal Contacts folders, you need to synchronize each folder individually.

Synchronization only supports full synchronization; all contacts in the specified folder are returned with each request.

Synchronizing a contacts folder typically requires two or more GET requests. You make the GET request much like the way you get contacts, except that you add the following request headers.

  • You must specify the Prefer: odata.track-changes header in all of your sync requests.

  • You may specify the Prefer: odata.maxpages={n} header to set the maximum number of contacts returned in each request.

    The second and subsequent GET requests differ from the first GET request by including either a deltaToken or a skipToken received in a previous response.

    The initial response to a sync request always returns a deltaToken. You should always make a second GET request using the deltaToken to determine if there are any additional contacts. The second request will return additional contacts and either a skipToken if there are more contacts available, or a deltaToken if the last contact was sent.

Minimum required scope

One of the following:

GET https://outlook.office.com/api/v2.0/me/Contacts
GET https://outlook.office.com/api/v2.0/me/ContactFolders/{folderName}
Required parameter Type Description
Header parameters
Prefer odata.track-changes Indicates that the request is a synchronization request.
Prefer odata.maxpagesize Sets the number of contacts returned in each response.
URL parameter
folderName string The name of the folder to synchronize.
odata.deltaLink String The token that indicates the last time that the folder was synchronized.
odata.skiptoken String The token that indicates that there are more messages to download.

Response type

A collection containing the requested contacts and a deltaToken that you use to request additional pages of contact data from server and to request an incremental synchronization. If the number of contacts returned is more than the value specified in the odata.maxpagesize header the response will be returned in multiple pages.

The response will include a Preference-Applied: odata-trackchanges header. If you attempt to sync a resource that is not supported, this header will not be returned in the response. Check for this header before processing the response to avoid errors.

Note

By default, the response includes all of the properties of the specified contacts. Use $select to specify only the properties that your need for best performance. The Id property is always returned. Do not use $filter, $orderby, $search or $top as they are not supported for synchronizing contacts or contact folders. See OData query parameters for further details.

Examples

Inital request for a full synchronization:

GET https://outlook.office.com/api/v2.0/Me/Contacts

Include the following headers:

  • Prefer: odata.track-changes
  • Prefer: odata.maxpagesize=100

Second request to the server after a full synchronization request:

https://outlook.office.com/api/v2.0/Me/Contacts/?%24deltatoken=169ca50467d34d9fb8adb664961b9836

Include the following headers:

  • Prefer: odata.track-changes
  • Prefer: odata.maxpagesize=100

Second response from the server with additional pages available:

Header

Preference-Applied: odata.track-changes

Body

@odata.deltaLink=https://outlook.office.com/api/v2.0/me/Contacts/messages/?%24skiptoken=169ca50467d34d9fb8adb664961b9836

Payload messages


Second or subsequent response from the server when all contacts have been sent:

Header

Preference-Applied: odata.track-changes

Body

@odata.deltaLink=https://outlook.office.com/api/v2.0/me/Contacts/?%24deltatoken=169ca50467d34d9fb8adb664961b9836

Payload messages


Request to server when additional pages are available:

https://outlook.office.com/api/v2.0/Me/Contacts/?%24skiptoken=169ca50467d34d9fb8adb664961b9836

Include the following headers.

  • Prefer: odata.track-changes
  • Prefer: odata.maxpagesize=100

Create contacts

Create a contact in the specified Contacts folder.

Create a contact

Minimum required scope

One of the following:

Add a contact to the root Contacts folder or to the contacts endpoint of another contact folder.

POST https://outlook.office.com/api/v2.0/me/contacts
POST https://outlook.office.com/api/v2.0/me/contactfolders/{contact_folder_id}/contacts
Required parameter Type Description
URL parameters
contact_folder_id string The contact folder ID, if you're creating a contact in a specific contact folder.
Body parameters
GivenName string The given name of the contact.

Specify the GivenName parameter and any writable contact properties in the request body.

Sample request

POST https://outlook.office.com/api/v2.0/me/contacts
Content-Type: application/json

{
  "GivenName": "Pavel",
  "Surname": "Bansky",
  "EmailAddresses": [
    {
      "Address": "pavelb@a830edad9050849NDA1.onmicrosoft.com",
      "Name": "Pavel Bansky"
    }
  ],
  "BusinessPhones": [
    "+1 732 555 0102"
  ]
}

Sample response

Status code: 201

{
  "@odata.context": "https://outlook.office.com/api/v2.0/$metadata#Me/Contacts/$entity",
  "@odata.id": "https://outlook.office.com/api/v2.0/Users('ddfcd489-628b-40d7-b48b-57002df800e5@1717622f-1d94-4d0c-9d74-709fad664b77')/Contacts('AAMkAGE0M4xqVAAA=')",
  "@odata.etag": "W/\"EQAAABYAAAAmP1Ln1wcHRariNdTMGAO9AAAV41eC\"",
  "Id": "AAMkAGE0M4xqVAAA=",
  "ChangeKey": "EQAAABYAAAAmP1Ln1wcHRariNdTMGAO9AAAV41eC",
  "Categories": [],
  "CreatedDateTime": "2014-10-22T20:38:18Z",
  "LastModifiedDateTime": "2014-10-22T20:38:19Z",
  "ParentFolderId": "AAMkAGE0MAAEOAAA=",
  "Birthday": null,
  "FileAs": "",
  "DisplayName": "Pavel Bansky",
  "GivenName": "Pavel",
  "Initials": null,
  "MiddleName": null,
  "NickName": null,
  "Surname": "Bansky",
  "Title": null,
  "Generation": null,
  "EmailAddresses": [
    {
      "Address": "pavelb@a830edad9050849NDA1.onmicrosoft.com",
      "Name": "Pavel Bansky"
    },
    null,
    null
  ],
  "ImAddresses": [
    null,
    null,
    null
  ],
  "JobTitle": null,
  "CompanyName": null,
  "Department": null,
  "OfficeLocation": null,
  "Profession": null,
  "BusinessHomePage": null,
  "AssistantName": null,
  "Manager": null,
  "HomePhones": [
    null,
    null
  ],
  "BusinessPhones": [
    "+1 732 555 0102",
    null
  ],
  "MobilePhone1": null,
  "HomeAddress": {
    "Street": null,
    "City": null,
    "State": null,
    "CountryOrRegion": null,
    "PostalCode": null
  },
  "BusinessAddress": {
    "Street": null,
    "City": null,
    "State": null,
    "CountryOrRegion": null,
    "PostalCode": null
  },
  "OtherAddress": {
    "Street": null,
    "City": null,
    "State": null,
    "CountryOrRegion": null,
    "PostalCode": null
  },
  "SpouseName": null,
  "PersonalNotes": null,
  "Children": [],
  "YomiSurname": null,
  "YomiGivenName": null,
  "YomiCompanyName": null
}

Response type

The new contact.

Update contacts

Change a contact's properties.

Update a contact

Minimum required scope

One of the following:

Specify any writable contact properties in the request body. Only the properties that you specify are changed.

PATCH https://outlook.office.com/api/v2.0/me/contacts/{contact_id}
Required parameter Type Description
URL parameters
contact_id string The contact ID.

Sample request

PATCH https://outlook.office.com/api/v2.0/me/contacts/AAMkAGI2THkzAAA=
Content-Type: application/json

{
  "HomeAddress": {
    "Street": "Some street",
    "City": "Seattle",
    "State": "WA",
    "PostalCode": "98121"
  },
  "Birthday": "1974-07-22"
}

Sample response

Status code: 200

{
  "@odata.context": "https://outlook.office.com/api/v2.0/$metadata#Me/Contacts/$entity",
  "@odata.id": "https://outlook.office.com/api/v2.0/Users('ddfcd489-628b-40d7-b48b-57002df800e5@1717622f-1d94-4d0c-9d74-709fad664b77')/Contacts('AAMkAGI2THkzAAA=')",
  "@odata.etag": "W/\"EQAAABYAAACd9nJ/tVysQos2hTfspaWRAAADTIa3\"",
  "Id": "AAMkAGI2THkzAAA=",
  "ChangeKey": "EQAAABYAAACd9nJ/tVysQos2hTfspaWRAAADTIa3",
  "Categories": [],
  "CreatedDateTime": "2014-10-19T23:08:18Z",
  "LastModifiedDateTime": "2014-10-19T23:08:18Z",
  "ParentFolderId": "AAMkAGI2AAEOAAA=",
  "Birthday": "1974-07-22T00:00:00Z",
  "FileAs": "Schorr, Janet",
  "DisplayName": "Janet Schorr",
  "GivenName": "Janet",
  "Initials": null,
  "MiddleName": null,
  "NickName": null,
  "Surname": "Schorr",
  "Title": null,
  "Generation": null,
  "EmailAddresses": [
    {
      "Address": "janets@a830edad9050849NDA1.onmicrosoft.com",
      "Name": "janets@a830edad9050849NDA1.onmicrosoft.com"
    },
    null,
    null
  ],
  "ImAddresses": [
    "sip:janets@a830edad9050849nda1.onmicrosoft.com",
    null,
    null
  ],
  "JobTitle": "Product Marketing Manager",
  "CompanyName": null,
  "Department": "Sales & Marketing",
  "OfficeLocation": "18/2111",
  "Profession": null,
  "BusinessHomePage": null,
  "AssistantName": null,
  "Manager": null,
  "HomePhones": [
    null,
    null
  ],
  "BusinessPhones": [
    "+1 425 555 0109",
    null
  ],
  "MobilePhone1": null,
  "HomeAddress": {
    "Street": "Some street",
    "City": "Seattle",
    "State": "WA",
    "CountryOrRegion": null,
    "PostalCode": "98121"
  },
  "BusinessAddress": {
    "Street": null,
    "City": null,
    "State": null,
    "CountryOrRegion": null,
    "PostalCode": null
  },
  "OtherAddress": {
    "Street": null,
    "City": null,
    "State": null,
    "CountryOrRegion": null,
    "PostalCode": null
  },
  "SpouseName": null,
  "PersonalNotes": null,
  "Children": [],
  "YomiSurname": null,
  "YomiGivenName": null,
  "YomiCompanyName": null
}

Response type

The updated contact.

Delete contacts

Delete a contact. Deleted contents might not be recoverable.

To learn more, see Deleting items by using EWS in Exchange.

Delete a contact

Minimum required scope

One of the following:

DELETE https://outlook.office.com/api/v2.0/me/contacts/{contact_id}
Required parameter Type Description
URL parameters
contact_id string The contact ID.

Sample request

DELETE https://outlook.office.com/api/v2.0/me/contacts/AAMkAGE0Myy2hAAA=

Sample response

Status code: 204

Get contact folders

You can get a contact folder collection or get a contact folder.

Get a contact folder collection

Minimum required scope

One of the following:

Get the contact folder collection under the default Contacts folder of the signed-in user (.../me/contactfolders), or under the specified contact folder.

GET https://outlook.office.com/api/v2.0/me/contactfolders
GET https://outlook.office.com/api/v2.0/me/contactfolders/{contact_folder_id}/childfolders

Note

See OData query parameters for filtering, sorting, and paging parameters.

Required parameter Type Description
URL parameters
contact_folder_id string The contact folder ID, if you're getting contact folders from a specific contact folder.

Sample request

GET https://outlook.office.com/api/v2.0/me/contactfolders

Sample response

Status code: 200

{
    "@odata.context": "https://outlook.office.com/api/v2.0/$metadata#Me/ContactFolders",
    "value": [
        {
            "@odata.id": "https://outlook.office.com/api/v2.0/Users('ddfcd489-628b-40d7-b48b-57002df800e5@1717622f-1d94-4d0c-9d74-709fad664b77')/ContactFolders('AAMkAGI2TKI5AAA=')",
            "Id": "AAMkAGI2TKI5AAA=",
            "ParentFolderId": "AAMkAGI2AAEOAAA=",
            "DisplayName": "Finance"
        }
    ]
}

Response type

The requested contact folder collection.

Get a contact folder

Minimum required scope

One of the following:

Get a contact folder by using the contact folder ID.

GET https://outlook.office.com/api/v2.0/me/contactfolders/{contact_folder_id}

Note

See OData query parameters for filtering, sorting, and paging parameters.

Required parameter Type Description
URL parameters
contact_folder_id string The contact folder ID.

Sample request

GET https://outlook.office.com/api/v2.0/me/contactfolders/AAMkAGI2TKI5AAA=

Sample response

Status code: 200

{
    "@odata.context": "https://outlook.office.com/api/v2.0/$metadata#Me/ContactFolders/$entity",
    "@odata.id": "https://outlook.office.com/api/v2.0/Users('ddfcd489-628b-40d7-b48b-57002df800e5@1717622f-1d94-4d0c-9d74-709fad664b77')/ContactFolders('AAMkAGI2TKI5AAA=')",
    "Id": "AAMkAGI2TKI5AAA=",
    "ParentFolderId": "AAMkAGI2AAEOAAA=",
    "DisplayName": "Finance"
}

Response type

The requested contact folder.

Get contact photo and metadata

Get contact photo

Minimum required scope

One of the following:

Get the photo of the specified signed-in user's contact.

GET https://outlook.office.com/api/v2.0/me/contacts('{contact_id}')/photo/$value
Required parameter Type Description
URL parameters
contact_id string The ID specifying the particular contact of the signed-in user's.

Sample request

GET https://outlook.office.com/api/v2.0/me/contacts('AAMkAGE1M2IyNGNm===')/photo/$value
Content-Type: image/jpg

Response data

Contains the binary data of the requested photo. The HTTP response code is 200.

The operation returns HTTP 404 if the contact does not already have a contact photo on Exchange Online.

Get contact photo metadata

Minimum required scope

One of the following:

Get the metadata of a contact photo, which includes the content type, width and height in pixels.

GET https://outlook.office.com/api/v2.0/me/contacts('{contact_id}')/photo
Required parameter Type Description
URL parameters
contact_id string The ID specifying the particular contact of the signed-in user's.

Sample request

GET https://outlook.office.com/api/v2.0/me/contacts('AAMkAGE1M2IyNGNm')/photo

Sample response data

A successful request returns HTTP 200.

{
    "@odata.context": "https://outlook.office.com/api/v2.0/$metadata#Me/Contacts('AAMkAGE1M2IyNGNm')/photo/$entity",
    "@odata.id": "https://outlook.office.com/api/v2.0/Users('ddfcd489-b826-40d7-b48b-57002df800e5@1717622f-49d1-4d0c-9d74-709fad664b77')/contacts('AAMkAGE1M2IyNGNm')/photo",
    "@odata.readLink": "https://outlook.office.com/api/v2.0/Users('ddfcd489-b826-40d7-b48b-57002df800e5@1717622f-49d1-4d0c-9d74-709fad664b77')/contacts('AAMkAGE1M2IyNGNm')/photo",
    "@odata.mediaContentType": "image/jpeg",
    "Id": "103X77",
    "Width": 103,
    "Height": 77
}

Set contact photo

Minimum required scope

One of the following:

Assign a photo to the specified signed-in user's contact. The photo should be in binary. It replaces any existing photo for that contact.

You can use PATCH or PUT for this operation in version 2.0.

PATCH https://outlook.office.com/api/v2.0/me/contacts('{contact_id}')/photo/$value

PUT https://outlook.office.com/api/v2.0/me/contacts('{contact_id}')/photo/$value
Required parameter Type Description
URL parameters
contact_id string The ID specifying the particular contact of the signed-in user's.

Sample request

PUT https://outlook.office.com/api/v2.0/me/contacts('AAMkAGE1M2IyNGNm===')/photo/$value
Content-Type: image/jpeg

Include the binary data of the photo in the request body.

Response data

A successful request returns HTTP 200.

Next steps

Whether you're ready to start building an app or just want to learn more, we've got you covered.

Or, learn more about using the Office 365 platform: