Update organizationalBrandingProperties

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.

Update the properties of an organizationalBrandingProperties object.

Permissions

One of the following permissions is required to call this API. To learn more, including how to choose permissions, see Permissions.

Permission type Permissions (from least to most privileged)
Delegated (work or school account) Organization.ReadWrite.All
Delegated (personal Microsoft account) Not supported.
Application Not supported.

HTTP request

PATCH /organization/{id}/branding/{property name}
PUT /organization/{id}/branding/{property name}

Request headers

Name Description
Authorization Bearer {token}. Required.
Content-Type application/json. Required.
Content-Language Locale. Optional.

Request body

In the request body, supply the values for relevant fields that should be updated. Existing properties that are not included in the request body will maintain their previous values or be recalculated based on changes to other property values. For best performance, don't include existing values that haven't changed.

Property Type Description
backgroundColor String Color that will appear in place of the background image in low-bandwidth connections. The primary color of your banner logo or your organization color is recommended to be used here. Specify this in hexadecimal (for example, white is #FFFFFF).
backgroundImage Stream Image that appears as the background of the sign in page. .png or .jpg not larger than 1920x1080 and smaller than 300kb. A smaller image will reduce bandwidth requirements and make page loads more performant.
bannerLogo Stream A banner version of your company logo which appears appears on the sign-in page. .png or .jpg no larger than 36x245px. We recommend using a transparent image with no padding around the logo.
signInPageText String Text that appears at the bottom of the sign-in box. You can use this to communicate additional information, such as the phone number to your help desk or a legal statement. This text must be Unicode and not exceed 1024 characters.
squareLogo Stream Square version of your company logo. This appears in Windows 10 out-of-box (OOBE) experiences and when Windows Autopilot is enabled for deployment. .png or .jpg no larger than 240x240px and no more than 10kb in size. We recommend using a transparent image with no padding around the logo.
usernameHintText String String that shows as the hint in the username textbox on the sign in screen. This text must be Unicode, without links or code, and can't exceed 64 characters.

The id property is ignored when passed in.

Response

If successful, this method returns a 204 OK response code.

Examples

Example 1: Update default branding

If the branding already exists, PATCH will replace only the specified properties, leaving unspecified properties unchanged.

Request

The following is an example of the request.

PATCH https://graph.microsoft.com/beta/organization/d69179bf-f4a4-41a9-a9de-249c0f2efb1d/branding
Content-Type: application/json

{
    "signInPageText":"Default",
    "usernameHintText":"DefaultHint"
}

Response

The following is an example of the response.

HTTP/1.1 204 OK

In this case, the values of the default /branding are updated but no values are changed on any localization.

Example 2: Update bannerLogo for default branding

The following request updates the banner logo for the default branding.

Request

The following is an example of the request.

PATCH https://graph.microsoft.com/beta/organization/d69179bf-f4a4-41a9-a9de-249c0f2efb1d/branding/bannerLogo
Content-Type: image/jpeg

<Image>

Response

The following is an example of the response.

HTTP/1.1 204 No Content

Example 3: Update localized branding

If Content-Language header is specified the localization associated with Content-Language is created, if it doesn't already exist, and then updated using the specified values. The default branding is not changed.

Request

The following is an example of the request.

PATCH https://graph.microsoft.com/beta/organization/d69179bf-f4a4-41a9-a9de-249c0f2efb1d/branding
Content-Type: application/json
Content-Language: fr

{
    "backgroundColor":"#FFFF33"
}

Response

The following is an example of the response.

HTTP/1.1 204 No Content

Following this request, the fr localization is updated with the new value of backgroundColor, but no change is made to the default /branding.

Example 4: Replace default branding and all localizations

If the branding already exists, PUT will replace the default branding and any localizations.

Request

The following is an example of the request.

PUT https://graph.microsoft.com/beta/organization/d69179bf-f4a4-41a9-a9de-249c0f2efb1d/branding
Content-Type: application/json
Content-Language: fr

{
    "backgroundColor":"#FFFF33"
}

Response

The following is an example of the response.

HTTP/1.1 204 No Content

Following this request, the default branding has only the backgroundColor specified and has exactly one localization with the id fr, also with the backgroundColor set.