Branding in ShareBase

NOTE: Library level branding and dynamic branding can only be taken advantage of when the New Link Experience & Dynamic Branding features are turned on. Please contact your account manager.

The API provides the ability to configure custom branding for shared link email messages, task email messages, web pages displaying shared content, and more. Currently, both deployment and library level branding are provided.

​Deployment level branding is branding that is applied across the entire deployment, and can be set up in the admin branding page. Documentation on configuring deployment level branding can be found at https://app.sharebase.com/help/

​Library level branding is new and can be applied per library. This new branding allows more control over how email messages and web pages are branded for external users outside your organization.

Setting up Deployment Level Branding

As a Site Admin, navigate to https://app.sharebase.com/admin. From there, in the side panel, there will be a branding section. This page will help you select the color, email header logo, web logo and more as well as giving you a preview. Once those values are set, a test email can be sent via the web client or the public API.

Library Level Branding

NOTE: Library branding relies on an underlying implementation of dynamic branding and currently only affects folder and document link shares within the corresponding library.

Setup a Dynamic Branding

There is currently no way to set up dynamic branding functionality within the web client. To create a dynamic branding, you will need to issue the following POST request using a Site Administrator Authorization token:

POST api/dynamic-brandings

With the following body

{
    "ApplicationName": "",
    "Base64EmailLogo": "",
    "Base64LoginLogo": "",
    "Base64WebLogo": "",
    "Description": "",
    "PrimaryColor": "",
    "SecondaryColor": "",
    "BackgroundColor":"",
    "Title": "",
    "SetAsFallback" : <bool>,
    "IsCustomBGColor": <bool>
}

• ApplicationName: The name of the process this branding is associated with. This cannot exceed 100 characters.
• Base64EmailLogo: The base64 encoded string of the logo that will be present in the email header.
  • The email logo MUST be a png.
• Base64LoginLogo: The base64 encoded string of the logo users will see during the authentication process for any shares.
  • The login logo MUST be a jpg/jpeg.
• Base64WebLogo: The base 64 encoded string of the logo the users will see while using the web app for their content.
  • The web logo MUST be a jpg/jpeg.
• Description: A description of the branding. This cannot exceed 300 characters.
• PrimaryColor: The string representation of the primary color of your brand, as a hexadecimal code, i.e. #AAFF33 or #AF3.
  • NOTE: While a preceding # is not necessary, the value must be a valid 3 or 6 hexadecimal digit code.
• Secondary color: The string representation of the secondary color of your brand, as a hexadecimal code, i.e. #AAFF33 or #AF3.
  • NOTE: While a preceding # is not necessary, the value must be a valid 3 or 6 hexadecimal digit code.
• BackgroundColor: The string representation of the background color of your brand, as a hexadecimal code, i.e. #AAFF33 or #AF3.
  • NOTE: Valid and required when IsCustomBGColor is true, otherwise will use the ShareBase default background color #E5E5E5. While a preceding # is not necessary, the value must be a valid 3 or 6 hexadecimal digit code.
• Title: The name/title given to the brand. This cannot exceed 100 characters.
• SetAsFallback: If the dynamic branding should be set as the default branding, which will get used for shares if branding was not configured for the library of the shared content.
• IsCustomBGColor: If custom background color should be used for branding. When this value is set to true, branding will use a custom background color specified in the required BackgroundColor. Otherwise, the branding will use the default background color in ShareBase, which is generic grey (#E5E5E5).

If the user is not a Site Admin, an HTTP 403 FORBIDDEN status code will be returned. When the call succeeds, and the branding is created, an HTTP 200 OK status code will be returned with a response similar to the following:

{
    "DynamicBrandingId": 1,
    "ApplicationName": "Workflow process for Recruitment",
    "Base64EmailLogo": "iVBORw0KGgoAAA...",
    "Base64LoginLogo": "/9j/2w...",
    "Base64WebLogo": "/9j/AA..",
    "Description": "The branding to be used for external emails from Recruitment",
    "PrimaryColor": "#FFA17A",
    "SecondaryColor": "#FFFFFF",
    "BackgroundColor": "#FFB17B",
    "Title": "Recruitment Branding",
    "IsFallback": true,
    "IsCustomBGColor": true,
}

Where:

• DynamicBrandingId: The ID of the dynamic brand.
• ApplicationName: The name of the process this branding is associated with. This cannot exceed 100 characters.
• Base64EmailLogo: The base64 encoded string of the logo that will be present in the email header.
  • This will be for a png.
• Base64LoginLogo: The base64 encoded string of the logo users will see during the authentication process for any shares.
  • This will be for a jpg/jpeg.
• Base64WebLogo: The base 64 encoded string of the logo the users will see while using the web app for their content.
  • This will be for a jpg/jpeg.
• Description: The description of the branding.
• PrimaryColor: The string representation of the primary color of your brand, as a hexadecimal code, i.e. #AAFF33 or #AF3.
  • NOTE: Even if the original request to create the branding did not contain a # preceding the hexadecimal code, this response will.
• Secondary color: The string representation of the secondary color of your brand, as a hexadecimal code, i.e. #AAFF33 or #AF3.
  • NOTE: Even if the original request to create the branding did not contain a # preceding the hexadecimal code, this response will.
• BackgroundColor: The string representation of the background color of your brand, as a hexadecimal code, i.e. #AAFF33 or #AF3.
  • NOTE: Even if the original request to create the branding did not contain a # preceding the hexadecimal code, this response will.
• Title: The name/title given to the brand.
• IsFallback: If the created dynamic brand is the default for the deployment.
• IsCustomBGColor: If custom background color should be used for branding.

Note that the PrimaryColor and SecondaryColor will both have a prepended # even if you did not include it in the original request, as this is the value that will be stored and used to ensure branding is applied properly.

An example uploading a new branding and creating an association using C# would look like the following script.

Associate the Dynamic Branding with a Library

To create a library branding, an association must be made between a dynamic branding and a library. This can be done by issuing the following POST request:

POST api/libraries/{libraryId}/branding

Where:

libraryId: The ID of the library you want to have the branding associated with

With the following body:

{
    "DynamicBrandingId": <integer>
}

• DynamicBrandingId: The ID of the dynamic branding to be associated with the library

If the user is not a Site Admin, an HTTP 403 FORBIDDEN status code will be returned. When the call succeeds, and the branding association is created, an HTTP 200 OK status code will be returned with a response similar to the following:

{
    "DynamicBrandingId": 1,
    "LibraryId": 1
}

Where:

DynamicBrandingId: The ID of the dynamic branding to be applied to link shares from the library. LibraryId: The ID of the library to have the branding applied to.

Once this association is made, document and link shares from the specified library will have their emails, login screens, and content screens branded with the specified branding.

Updating the Branding

The API also provides the ability to update existing brandings, at both the dynamic branding and library branding level.

Updating the Dynamic Branding

Updating the dynamic branding will allow for the changing of individual logos and colors, as well as descriptors such as the title. This can be done by issuing the following PUT request:

PUT api/dynamic-brandings/{id}

Where:

id: The ID of the dynamic branding you want to update

With the following body:

{
    "ApplicationName": "",
    "Base64EmailLogo": "",
    "Base64LoginLogo": "",
    "Base64WebLogo": "",
    "Description": "",
    "PrimaryColor": "",
    "SecondaryColor": "",
    "BackgroundColor": "",
    "Title": "",
    "SetAsFallback" : <bool>,
    "IsCustomBGColor" : <bool>
}

Where:

• ApplicationName: The name of the process this branding is associated with. This cannot exceed 100 characters.
• Base64EmailLogo: The base64 encoded string of the logo that will be present in the email header.
  • The email logo MUST be a png.
• Base64LoginLogo: The base64 encoded string of the logo users will see during the authentication process for any shares.
  • The login logo MUST be a jpg/jpeg.
• Base64WebLogo: The base 64 encoded string of the logo the users will see while using the web app for their content.
  • The web logo MUST be a jpg/jpeg.
• Description: A description of the branding. This cannot exceed 300 characters.
• PrimaryColor: The string representation of the primary color of your brand, as a hexadecimal code, i.e. #AAFF33 or #AF3.
  • NOTE: While a preceding # is not necessary, the value must be a valid 3 or 6 hexadecimal digit code.
• Secondary color: The string representation of the secondary color of your brand, as a hexadecimal code, i.e. #AAFF33 or #AF3.
  • NOTE: While a preceding # is not necessary, the value must be a valid 3 or 6 hexadecimal digit code.
• BackgroundColor: The string representation of the background color of your brand, as a hexadecimal code, i.e. #AAFF33 or #AF3.
  • NOTE: Valid and required when IsCustomBGColor is true, otherwise will use the ShareBase default background color #E5E5E5. While a preceding # is not necessary, the value must be a valid 3 or 6 hexadecimal digit code.
• Title: The name/title given to the brand. This cannot exceed 100 characters.
• SetAsFallback: If the dynamic branding should be set as the default branding, which will get used for shares if branding was not configured for the library of the shared content.
• IsCustomBGColor: If custom background color should be used for branding. When this value is set to true, branding will use a custom background color specified in the required BackgroundColor. Otherwise, the branding will use the default background color in ShareBase, which is generic grey (#E5E5E5).

The body must have all of the attributes, even if they are the same. This makes it so multiple values can be updated at the same time.

If the user is not a Site Admin, an HTTP 403 FORBIDDEN status code will be returned. When the call succeeds, and the branding is updated, an HTTP 200 OK status code will be returned with a response similar to the following:

{
    "DynamicBrandingId": 1,
    "ApplicationName": "Workflow process for Recruitment",
    "Base64EmailLogo": "iVBORw0KGgoAAA...",
    "Base64LoginLogo": "/9j/2w...",
    "Base64WebLogo": "/9j/AA..",
    "Description": "The branding to be used for external emails from Recruitment",
    "PrimaryColor": "#FFA17A",
    "SecondaryColor": "#FFFFFF",
    "BackgroundColor": "#FFB17B",
    "Title": "Recruitment Branding",
    "IsFallback": true,
    "IsCustomBGColor": true
}

Where:

• DynamicBrandingId: The ID of the DynamicBranding
• ApplicationName: The name of the process this branding is associated with. This cannot exceed 100 characters.
• Base64EmailLogo: The base64 encoded string of the logo that will be present in the email header.
  • This will be for a png.
• Base64LoginLogo: The base64 encoded string of the logo users will see during the authentication process for any shares.
  • This will be for a jpg/jpeg.
• Base64WebLogo: The base 64 encoded string of the logo the users will see while using the web app for their content.
  • This will be for a jpg/jpeg.
• Description: The description of the branding.
• PrimaryColor: The string representation of the primary color of your brand, as a hexadecimal code, i.e. #AAFF33 or #AF3.
  • NOTE: Even if the original request to create the branding did not contain a # preceding the hexadecimal code, this response will.
• Secondary color: The string representation of the secondary color of your brand, as a hexadecimal code, i.e. #AAFF33 or #AF3.
  • NOTE: Even if the original request to create the branding did not contain a # preceding the hexadecimal code, this response will.
• BackgroundColor: The string representation of the background color of your brand, as a hexadecimal code, i.e. #AAFF33 or #AF3.
  • NOTE: Even if the original request to create the branding did not contain a # preceding the hexadecimal code, this response will.
• Title: The name/title given to the brand.
• IsFallback: If the created dynamic brand is the default for the deployment.
• IsCustomBGColor: If custom background color should be used for branding.

Updating the Library Branding

You can update the library branding to associate a different dynamic dranding with the specified library. This can be done by issuing the following PUT request:

PUT api/libraries/{libraryId}/branding

Where:

libraryId: The ID of the Library you want to create the branding association

With the following body:

{
    "DynamicBrandingId": <integer>
}

• DynamicBrandingId: The ID of the dynamic branding to be associated with the library

This will change the library to have a new branding applied to link shares contain within the specified library. If the user is not a Site Admin, an HTTP 403 FORBIDDEN status code will be returned. When the call succeeds, and the branding association is created, an HTTP 200 OK status code will be returned with a response similar to the following:

{
    "DynamicBrandingId": 1,
    "LibraryId": 1
}

Where:

DynamicBrandingId: The ID of the dynamic branding to be applied to link shares from the library. LibraryId: The ID of the library to have the branding applied to.

Viewing all Brandings

Currently, we support viewing all dynamic brandings in the form of an HTTP response. This can be done by issuing the following GET request:

GET api/dynamic-brandings

If the user is not a Site Admin, an HTTP 403 FORBIDDEN status code will be returned for the response. If the user is a Site admin, an HTTP 200 OK status code will be returned with a response body like so:

[
    {
        "DynamicBrandingId": 1,
        "ApplicationName": "Workflow process for Recruitment",
        "Base64EmailLogo": "iVBORw0KGgoAAA...",
        "Base64LoginLogo": "/9j/2w...",
        "Base64WebLogo": "/9j/AA..",
        "Description": "The branding to be used for external emails from Recruitment",
        "PrimaryColor": "#FFA17A",
        "SecondaryColor": "#FFFFFF",
        "Title": "Recruitment Branding",
        "IsFallback": true
    },
    {
        "DynamicBrandingId": 2,
        "ApplicationName": "Workflow process for Marketing",
        "Base64EmailLogo": "iVBORw0KGgocR3...",
        "Base64LoginLogo": "/9j/C2...",
        "Base64WebLogo": "/9j/AA..",
        "Description": "The branding to be used for external emails from Marketing",
        "PrimaryColor": "#003366",
        "SecondaryColor": "#OD98BA",
        "Title": "Marketing Branding",
        "IsFallback": false
    },
    ...
]

Where:

• DynamicBrandingId: The ID of the DynamicBranding
• ApplicationName: The name of the process this branding is associated with. This cannot exceed 100 characters.
• Base64EmailLogo: The base64 encoded string of the logo that will be present in the email header.
  • This will be for a png.
• Base64LoginLogo: The base64 encoded string of the logo users will see during the authentication process for any shares.
  • This will be for a jpg/jpeg.
• Base64WebLogo: The base 64 encoded string of the logo the users will see while using the web app for their content.
  • This will be for a jpg/jpeg.
• Description: The description of the branding.
• PrimaryColor: The string representation of the primary color of your brand, as a hexadecimal code, i.e. #AAFF33 or #AF3.
  • NOTE: Even if the original request to create the branding did not contain a # preceding the hexadecimal code, this response will.
• Secondary color: The string representation of the secondary color of your brand, as a hexadecimal code, i.e. #AAFF33 or #AF3.
  • NOTE: Even if the original request to create the branding did not contain a # preceding the hexadecimal code, this response will.
• Title: The name/title given to the brand.
• IsFallback: If the created dynamic brand is the default for the deployment.

Deleting Brandings

Brandings can be deleted at both the library branding association and dynamic branding levels. If a dynamic branding is deleted, the library branding association will also be deleted, and the specific library will no longer have the branding applied.

Deleting a Dynamic Branding

To delete a dynamic branding, send the following DELETE request:

DELETE api/dynamic-brandings

If the user is not a Site Admin, an HTTP 403 FORBIDDEN status code will be returned. If the dynamic branding does not exist, an HTTP 404 NOT FOUND status code will be returned. When the call succeeds, and the branding is deleted, an HTTP 200 OK status code will be returned.

Deleting a Library Branding

To delete a library branding, send the following DELETE request

DELETE api/libraries/{libraryId}/branding

Where:

libraryId: The ID of the library to remove the association from.

If the user is not a Site Admin, an HTTP 403 FORBIDDEN status code will be returned. If the library branding OR library does not exist, an HTTP 404 NOT FOUND status code will be returned. When the call succeeds, and the branding is deleted, an HTTP 200 OK status code will be returned.

Testing the Email Branding

After you have your branding set up, you can test your branding by sending a POST request to the following endpoint:

POST api/dynamic-brandings/{id}/test-branding

Where:

id: The ID of dynamic branding to be tested.

If the user is not a Site Admin, an HTTP 403 FORBIDDEN status code will be returned for the response. If the user is a Site admin, an HTTP 200 OK status and an email will be sent to the user with the branding applied.

Setting the Default Branding

To set an already existing dynamic branding as the default for link shares without branding explicitly configured, you can send a POST request to the following endpoint:

POST api/dynamic-brandings/{id}/fallback

Where:

id: The ID of dynamic branding to be set as the default.

If the user is not a Site Admin, an HTTP 403 FORBIDDEN status code will be returned for the response. If the dynamic branding corresponding to the ID does not exist, an HTTP 404 NOT FOUND status code will be returned. If the user is a Site Admin, and the branding exists, an HTTP 200 OK status will be returned, and the branding will be set as a default brand.

Seeing the Current Default Branding

To see the current default brand, you can send a GET request to the following endpoint:

GET api/dynamic-brandings/fallback

Any authenticated user can send a request to this endpoint. If a default brand does not exist, an HTTP 404 NOT FOUND status will be returned for the response. Otherwise an HTTP 200 OK status will be returned with a response similar to the following:

{
    "DynamicBrandingId": 1,
    "ApplicationName": "Workflow process for Recruitment",
    "Base64EmailLogo": "iVBORw0KGgoAAA...",
    "Base64LoginLogo": "/9j/2w...",
    "Base64WebLogo": "/9j/AA..",
    "Description": "The branding to be used for external emails from Recruitment",
    "PrimaryColor": "#FFA17A",
    "SecondaryColor": "#FFFFFF",
    "Title": "Recruitment Branding",
    "IsFallback": true
}

Where:

• DynamicBrandingId: The ID of the DynamicBranding
• ApplicationName: The name of the process this branding is associated with. This cannot exceed 100 characters.
• Base64EmailLogo: The base64 encoded string of the logo that will be present in the email header.
  • This will be for a png.
• Base64LoginLogo: The base64 encoded string of the logo users will see during the authentication process for any shares.
  • This will be for a jpg/jpeg.
• Base64WebLogo: The base 64 encoded string of the logo the users will see while using the web app for their content.
  • This will be for a jpg/jpeg.
• Description: The description of the branding.
• PrimaryColor: The string representation of the primary color of your brand, as a hexadecimal code, i.e. #AAFF33 or #AF3.
  • NOTE: Even if the original request to create the branding did not contain a # preceding the hexadecimal code, this response will.
• Secondary color: The string representation of the secondary color of your brand, as a hexadecimal code, i.e. #AAFF33 or #AF3.
  • NOTE: Even if the original request to create the branding did not contain a # preceding the hexadecimal code, this response will.
• Title: The name/title given to the brand.
• IsFallback: If the created dynamic brand is the default for the deployment. Always true on a HTTP 200 OK response.

Removing the Default Branding

To remove the current default branding, you can send a DELETE request to the following endpoint:

DELETE api/dynamic-brandings/{id}/fallback

Where:

id: The ID of dynamic branding to be removed as the default branding.

If the user is not a Site Admin, an HTTP 403 FORBIDDEN status code will be returned for the response. If the dynamic branding corresponding to the ID does not exist, or the corresponding dynamic branding is not the default branding, an HTTP 404 NOT FOUND status code will be returned. If the user is a Site Admin, and the default branding exists, an HTTP 200 OK status will be returned, and the default branding will be removed.