[DEPRECATED] Outlook User Photo REST API reference (beta)

  • Article

Applies to: Exchange Online | Office 365

Note

The beta version of the Outlook REST API is deprecated.

As announced on November 17, 2020, version 2.0 of the Outlook REST API has been deprecated. Consequently, the beta REST endpoint is also deprecated and will be fully decommissioned in November 2022. 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 the beta version 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.

In addition to the photo entity, the User Photo API provides a photos collection that is in preview and available only in the beta version. The photos collection lets you indicate specific sizes of the user photo that you're interested in.

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/beta/me/photo
GET https://outlook.office.com/api/beta/Users('{user_id}')/photo

Get the metadata for all available photo sizes

GET https://outlook.office.com/api/beta/me/photos
GET https://outlook.office.com/api/beta/Users('{user_id}')/photos

Get the metadata for a specific photo size

GET https://outlook.office.com/api/beta/me/photos('{size}')
GET https://outlook.office.com/api/beta/Users('{user_id}')/photos('{size}')
Optional parameter Type Description
Url parameters
user_id string The user's email address.
size string A photo size. The value of '1x1' is autogenerated in the case a photo is not present in both Active Directory and the mailbox.

If the photo is stored in the mailbox, then the predefined sizes are: '48x48', '64x64', '96x96', '120x120', '240x240', '360x360','432x432', '504x504', and '648x648'. If the user doesn't upload a large enough photo, then only the sizes that can be represented by the smaller predefined sizes are available. For example, if the user uploads a photo that is 504x504 pixels, then all but the 648x648 size of photo will be available for download.

Photos can by any dimension if they are stored in Active Directory.

Sample request

This request gets the metadata for 240x240 pixel image for the signed-in user.

GET https://outlook.office.com/api/beta/me/photos('240x240')

Sample response data

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

{
    "@odata.context": "https://outlook.office.com/api/beta/$metadata#Me/photo/$entity",
    "@odata.id": "https://outlook.office.com/api/beta/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/beta/$metadata#Me/photo/$entity",
    "@odata.id": "https://outlook.office.com/api/beta/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/beta/me/photo/$value
GET https://outlook.office.com/api/beta/Users('{user_id}')/photo/$value

Get the photo of a specific size

GET https://outlook.office.com/api/beta/me/photos('{size}')/$value
GET https://outlook.office.com/api/beta/Users('{user_id}')/photos('{size}')/$value
Optional parameter Type Description
Url parameters
user_id string The user's email address.
size string A photo size. The value of '1x1' is autogenerated in the case a photo is not present in both Active Directory and the mailbox.

If the photo is stored in the mailbox, then the predefined sizes are: '48x48', '64x64', '96x96', '120x120', '240x240', '360x360','432x432', '504x504', and '648x648'. If the user doesn't upload a large enough photo, then only the sizes that can be represented by the smaller predefined sizes are available. For example, if the user uploads a photo that is 504x504 pixels, then all but the 648x648 size of photo will be available for download.

Photos can by any dimension if they are stored in Active Directory.

Sample request

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

GET https://outlook.office.com/api/beta/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 specified user. The photo should be in binary. It replaces any existing photo for that user.

This operation allows a tenant administrator to let an app set the user photo of any user in the tenant. Use only PUT for this operation in the beta version.

Required scope

Use the following scope to set the photo of the specified user, who can be any user in the tenant or the signed-in user:

  • user.readwrite.all

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

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

Sample request

PUT https://outlook.office.com/api/beta/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: