Share via

[DEPRECATED] Outlook User Photo REST API reference (version 2.0)

  • Article

Applies to: Exchange Online | Office 365

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 User Photo API lets you download or set the photo of a user whose mailbox is secured by Azure Active Directory on Office 365.

Note

The User Photo API does not support consumer mailboxes in Microsoft account domains, such as Hotmail.com, Live.com, MSN.com, Outlook.com, and Passport.com.

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.

Using the User Photo REST API

Authentication

Like other Outlook REST API, for every request to the Outlook User Photo 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 User Photo API.

Version of API

This API has been promoted from preview to General Availability (GA) status. It is supported in the v2.0 and beta versions of the Outlook REST API.

Target user

The target user can be the signed-in user, or a user specified by a user ID.

For more information using this API, and information common to all subsets of the Outlook REST API, see Use the Outlook REST API.

User photo operations

The user photo operations allow you to get a user's photo metadata and photo stream in binary format and set the user photo.

Get photo metadata

Get information about the requested user photo, which includes the content type, eTag, and width and height in pixels.

Required scope

Use one of the following scopes to get photo metadata of the specified user, who can be the signed-in user:

  • user.readbasic.all
  • user.read.all
  • user.readwrite.all

You can also use the following scope to get photo metadata of specifically the signed-in user:

  • user.read

Get the metadata for the largest available photo

GET https://outlook.office.com/api/v2.0/me/photo
GET https://outlook.office.com/api/v2.0/Users('{user_id}')/photo
Optional parameter Type Description
Url parameters
user_id string The user's email address.

Sample request

This request gets the metadata of the user photo of the signed-in user.

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

Sample response data

The following response data shows the photo metadata. The HTTP response code is 200.

{
    "@odata.context": "https://outlook.office.com/api/v2.0/$metadata#Me/photo/$entity",
    "@odata.id": "https://outlook.office.com/api/v2.0/Users('ddfcd489-628b-7d04-b48b-20075df800e5@1717622f-1d94-c0d4-9d74-f907ad6677b4')/photo",
    "@odata.mediaContentType": "image/jpeg",
    "@odata.mediaEtag": "\"BA09D118\"",
    "Id": "240X240",
    "Width": 240,
    "Height": 240
}

The following response data shows the contents of a response when a photo hasn't already been uploaded for the user. The HTTP response code is a 200.

{
    "@odata.context": "https://outlook.office.com/api/v2.0/$metadata#Me/photo/$entity",
    "@odata.id": "https://outlook.office.com/api/v2.0/Users('ddfcd489-628b-7d04-b48b-20075df800e5@1717622f-1d94-c0d4-9d74-f907ad6677b4')/photo",
    "@odata.mediaContentType": "image/gif",
    "@odata.mediaEtag": "",
    "Id": "1X1",
    "Width": 1,
    "Height": 1
}

Get photo

Get the user photo of the specified user.

This operation allows a tenant administrator to let an app get the user photo of any user in the tenant.

Required scope

Use one of the following scopes to get the photo of the specified user, who can be the signed-in user:

  • user.readbasic.all
  • user.read.all
  • user.readwrite.all

You can also use the following scope to get the photo of specifically the signed-in user:

  • user.read
  • user.readwrite

Get the largest available size

GET https://outlook.office.com/api/v2.0/me/photo/$value
GET https://outlook.office.com/api/v2.0/Users('{user_id}')/photo/$value
Optional parameter Type Description
Url parameters
user_id string The user's email address.

Sample request

This request gets the photo for the signed-in user.

GET https://outlook.office.com/api/v2.0/me/photo/$value
Content-Type: image/jpg

Response data

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

Set user photo

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

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

Required scope

Use the following scope to set the photo of the signed-in user:

  • user.readwrite
PATCH https://outlook.office.com/api/v2.0/me/photo/$value
PATCH https://outlook.office.com/api/v2.0/users('{user_id}')/photo/$value

PUT https://outlook.office.com/api/v2.0/me/photo/$value
PUT https://outlook.office.com/api/v2.0/users('{user_id}')/photo/$value
Optional parameter Type Description
Url parameters
user_id string The user's email address.

Sample request

PATCH https://outlook.office.com/api/v2.0/me/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: