Create organizationalBrandingProperties


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.

Create an organizationalBrandingProperties object. This creates the default branding and optionally a localized branding at the same time. The default branding is loaded when a localized branding set isn't configured for the user's browser language.


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

A branding is created for an organization, if one does not already exist, using PUT or PATCH.

If branding is already configured, PUT will overwrite all existing values regardless of what's in the request body. PATCH will only overite the values that are included in the request body, leaving the values not included unchanged.

The id property is ignored on PUT/PATCH to the /branding singleton. If Content-Language is not specified, the default branding is created, which corresponds to an id of und. If Content-Language is specified, branding is created for that locale.

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

Optional query parameters

This method supports some of the OData query parameters to help customize the response. For general information, see OData query parameters.

Request headers

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

Request body

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.


If successful, this method returns a 201 Created response code and the created organizationalBrandingProperties object in the response body.


The following example creates default branding and localization for en-US.


The following is an example of the request.

Content-Type: application/json
Content-Language: en-US



The following is an example of the response.

HTTP/1.1 201 Created
Content-Type: application/json
Content-Language: en-US

    "backgroundImage@odata.mediaReadLink": "",
    "backgroundImage@odata.mediaEditLink": "",
    "bannerLogo@odata.mediaReadLink": "",
    "bannerLogo@odata.mediaEditLink": "",
    "id": "und",
    "squareLogo@odata.mediaReadLink": "",
    "squareLogo@odata.mediaEditLink": "",

In this case, the default branding object is set. Localized branding for en-US is also set due to the Content-Language in the header, even though the en-US branding set is not returned in the response. Note that Content-Language in the request is optional, and if not present, will only set default branding.