[DEPRECATED] Outlook User Photo REST API reference (beta)
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: