Edit

Share via

Get profilePhoto

  • Article

Namespace: microsoft.graph

Important

APIs under the /beta version in Microsoft Graph are subject to change. Use of these APIs in production applications is not supported. To determine whether an API is available in v1.0, use the Version selector.

Get the specified profilePhoto or its metadata (profilePhoto properties) from Microsoft 365.

Note: When attempting to GET a user photo, this operation first tries to retrieve the specified photo from Microsoft 365. If the photo is unavailable in Microsoft 365, the API trie to retrieve the photo from Microsoft Entra ID.

The supported sizes of HD photos in Microsoft 365 are as follows: 48x48, 64x64, 96x96, 120x120, 240x240, 360x360, 432x432, 504x504, and 648x648. Photos can be any dimension if they're stored in Microsoft Entra ID.

You can get the metadata of the largest available photo or specify a size to get the metadata for that photo size. If the size you request is unavailable, you can still get a smaller size that the user has uploaded and made available. For example, if the user uploads a photo that is 504x504 pixels, all but the 648x648 photo size is available for download. If the specified size is unavailable in the user's mailbox or Microsoft Entra ID, the size 1x1 is returned with the rest of the metadata.

This API is available in the following national cloud deployments.

Global service US Government L4 US Government L5 (DOD) China operated by 21Vianet
✅ ✅ ✅ ✅

Permissions

The following tables show the least privileged permission or permissions required to call this API on each supported resource type. Follow best practices to request the least privileged permissions. For details about delegated and application permissions, see Permission types. To learn more about these permissions, see the permissions reference.

To retrieve the profile photo of a contact

Permission type Least privileged permissions Higher privileged permissions
Delegated (work or school account) Contacts.Read Contacts.ReadWrite
Delegated (personal Microsoft account) Contacts.Read Contacts.ReadWrite
Application Contacts.Read Contacts.ReadWrite

To retrieve the profile photo of a group

Permission type Least privileged permissions Higher privileged permissions
Delegated (work or school account) ProfilePhoto.Read.All ProfilePhoto.ReadWrite.All, Group.Read.All, Group.ReadWrite.All
Delegated (personal Microsoft account) Not supported. Not supported.
Application ProfilePhoto.Read.All ProfilePhoto.ReadWrite.All, Group.Read.All, Group.ReadWrite.All

To retrieve the profile photo of a team

Permission type Least privileged permissions Higher privileged permissions
Delegated (work or school account) Team.ReadBasic.All TeamSettings.Read.All, TeamSettings.ReadWrite.All
Delegated (personal Microsoft account) Not supported. Not supported.
Application Team.ReadBasic.All TeamSettings.Read.All, TeamSettings.ReadWrite.All

To retrieve the profile photo of a user

Permission type Least privileged permissions Higher privileged permissions
Delegated (work or school account) ProfilePhoto.Read.All ProfilePhoto.ReadWrite.All, User.Read, User.ReadBasic.All, User.Read.All, User.ReadWrite, User.ReadWrite.All
Delegated (personal Microsoft account) User.Read User.ReadWrite
Application ProfilePhoto.Read.All ProfilePhoto.ReadWrite.All, User.Read.All, User.ReadWrite.All

Note

  • Retrieving a user's photo using the Microsoft Graph API is currently not supported in Azure AD B2C tenants.

HTTP request

Get the photo

GET /me/photo/$value
GET /users/{id | userPrincipalName}/photo/$value
GET /groups/{id}/photo/$value
GET /me/contacts/{id}/photo/$value
GET /users/{id | userPrincipalName}/contacts/{id}/photo/$value
GET /me/contactfolders/{contactFolderId}/contacts/{id}/photo/$value
GET /users/{id | userPrincipalName}/contactfolders/{contactFolderId}/contacts/{id}/photo/$value
GET /team/{id}/photo/$value

Get the metadata of the photo

GET /me/photo
GET /me/photos
GET /users/{id | userPrincipalName}/photo
GET /groups/{id}/photo
GET /me/contacts/{id}/photo
GET /users/{id | userPrincipalName}/contacts/{id}/photo
GET /me/contactfolders/{contactFolderId}/contacts/{id}/photo
GET /users/{id | userPrincipalName}/contactfolders/{contactFolderId}/contacts/{id}/photo
GET /team/{id}/photo

Get the metadata for a specific photo size

GET /me/photos/{size}
GET /users/{id | userPrincipalName}/photos/{size}
GET /groups/{id}/photos/{size}

Path parameters

Parameter Type Description
size String A photo size. The supported sizes of HD photos on Microsoft 365 are as follows: 48x48, 64x64, 96x96, 120x120, 240x240, 360x360, 432x432, 504x504, and 648x648. Photos can be any dimension if they're stored in Microsoft Entra ID.

Optional query parameters

This method supports the OData query parameters to help customize the response.

Request headers

Name Type Description
Authorization string Bearer {token}. Required. Learn more about authentication and authorization.

Request body

Don't supply a request body for this method.

Response

Response for getting the photo

If successful, this method returns a 200 OK response code and binary data of the requested photo. If no photo exists, the operation returns 404 Not Found.

Response for getting the metadata of the photo

If successful, this method returns a 200 OK response code and profilePhoto object in the response body.

Examples

Example 1: Get the photo for the signed-in user in the largest available size

Request

The following example shows a request.

GET https://graph.microsoft.com/beta/me/photo/$value
Content-Type: image/jpg

Response

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

HTTP/1.1 200 OK

Example 2: Get the 48x48 photo for the signed-in user

Request

The following example shows a request.

GET https://graph.microsoft.com/beta/me/photos/48x48/$value
Content-Type: image/jpg

Note

  • To ensure a fixed size for the output photo, use the dedicated endpoint for photos with fixed sizes (/photos) instead of relying on the default photo endpoint, which provides the largest available photo (/photo).

Response

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

HTTP/1.1 200 OK

Example 3: Get the metadata of the user photo of the signed-in user

Request

The following example shows a request.

GET https://graph.microsoft.com/beta/me/photo

Response

The following response data shows the photo metadata.

Note: The response object shown here might be shortened for readability.

HTTP/1.1 200 OK
Content-type: application/json

{
    "@odata.context": "https://graph.microsoft.com/beta/$metadata#Me/photo/$entity",
    "@odata.id": "https://graph.microsoft.com/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.

Note: The response object shown here might be shortened for readability.

HTTP/1.1 200 OK
Content-type: application/json

{
    "@odata.context": "https://graph.microsoft.com/beta/$metadata#Me/photo/$entity",
    "@odata.id": "https://graph.microsoft.com/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
}

Example 4: Get the metadata of the team photo

Request

The following example shows a request to get the metadata of the team photo.

GET https://graph.microsoft.com/beta/teams/172b0cce-e65d-44ce-9a49-91d9f2e8491e/photo

Response

The following example shows the response.

Note: The response object shown here might be shortened for readability.

HTTP/1.1 200 OK
Content-type: application/json

{
    "@odata.context": "https://graph.microsoft.com/beta/$metadata#teams('172b0cce-e65d-44ce-9a49-91d9f2e8491e')/photo/$entity",
    "@odata.id": "https://graph.microsoft.com/beta/teams('172b0cce-e65d-44ce-9a49-91d9f2e8491e')/photo",
    "@odata.mediaContentType": "image/jpeg",
    "@odata.mediaEtag": "\"BA09D118\"",
    "id": "240X240",
    "width": 240,
    "height": 240
}

Example 5: Get the team photo's binary data

The following example shows a request to get the team photo's binary data.

Request

GET https://graph.microsoft.com/beta/teams/172b0cce-e65d-44ce-9a49-91d9f2e8491e/photo/$value

Response

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

HTTP/1.1 200 OK

Using the binary data of the requested photo

When you use the /photo/$value endpoint to get the binary data for a profile photo, you need to convert the data into a base-64 string to add it as an email attachment. The following JavaScript example shows how to create an array that you can pass as the value of the Attachments parameter of an Outlook message.

const attachments = [{
  '@odata.type': '#microsoft.graph.fileAttachment',
  ContentBytes: file.toString('base64'),
  Name: 'mypic.jpg'
}];

For implementation details, see the Microsoft Graph Connect Sample for Node.js.

If you want to display the image on a web page, create an in-memory object from the image and make that object the source of an image element. The following JavaScript example shows this operation.

const url = window.URL || window.webkitURL;
const blobUrl = url.createObjectURL(image.data);
document.getElementById(imageElement).setAttribute("src", blobUrl);