Customizing your Branding with the API

Custom branding lets you display your company logo, name, and website in the Portal for your managed accounts.
For more information about custom branding, see Adding Custom Branding. The branding profile API lets you create, retrieve, and update custom branding.

Prerequisites

Before you begin, ensure that you have a valid access token. For more information, see Creating an API Key.

Authorization requirements

The branding profile endpoints have the following authorization requirements:

Endpoint	Account Type
GET (Retrieve)	Partner or Managed Account
POST (Create)	Partner only
PUT (Update)	Partner only

When a managed account retrieves a branding profile, the API returns the parent partner’s branding profile.

Retrieving a branding profile

To retrieve a branding profile, send a GET request to /v3/companies/{companyUid}/branding-profile.

Response

A successful request returns a 200 OK response with the branding profile details:

Field	Type	Description
`companyBrandingName`	string	The display name for branding.
`primaryLogoKey`	string	The storage key for the uploaded logo image.
`webUrl`	string	The company website URL.

Example response

{
  "message": "Branding profile found",
  "data": {
    "companyBrandingName": "Partner Company",
    "primaryLogoKey": "primary/a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "webUrl": "https://partner-company.com"
  }
}

Error responses

Code	Description
`401 Unauthorized`	Authentication required.
`403 Forbidden`	The user’s account type is not Partner or Managed Account.

Creating a branding profile

To create a branding profile, send a POST request to /v3/companies/{companyUid}/branding-profile.

Request

Parameter	Type	Required	Description
`companyBrandingName`	string	Yes	The display name for branding. Must be 1-80 characters and cannot be blank or whitespace-only.
`primaryLogoImage`	string	Yes	The logo image as a base64-encoded data URI. Format: `data:image/\{type};base64,\{encoded-data}`. Supported image types: PNG, JPEG, SVG, and WebP. Maximum size: 2 MB.
`webUrl`	string	Yes	The company website URL. Must be a valid URL including the protocol (`http://` or `https://`).

Example request body

{
  "companyBrandingName": "Partner Company",
  "primaryLogoImage": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mNk+M9QDwADhgGAWjR9awAAAABJRU5ErkJggg==",
  "webUrl": "https://partner-company.com"
}

Response

A successful request returns a 201 Created response with the branding profile details:

Field	Type	Description
`companyBrandingName`	string	The display name for branding.
`primaryLogoKey`	string	The storage key for the uploaded logo image.
`webUrl`	string	The company website URL.

Example response

{
  "message": "Branding profile created successfully",
  "data": {
    "companyBrandingName": "Partner Company",
    "primaryLogoKey": "primary/a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "webUrl": "https://partner-company.com"
  }
}

Error responses

Code	Description
`400 Bad Request`	Invalid request parameters. Common causes: blank or whitespace-only branding name, invalid logo format or encoding, logo exceeds 2 MB, or invalid URL format.
`401 Unauthorized`	Authentication required.
`403 Forbidden`	User must be a Company Admin in the partner account.

Updating a branding profile

To update a branding profile, send a PUT request to /v3/companies/{companyUid}/branding-profile.

Request

Parameter	Type	Required	Description
`companyBrandingName`	string	Yes	The display name for branding. Must be 1-80 characters and cannot be blank or whitespace-only.
`primaryLogoImage`	string	No	The logo image as a base64-encoded data URI. Format: `data:image/\{type};base64,\{encoded-data}`. Supported image types: PNG, JPEG, SVG, and WebP. Maximum size: 2 MB. Only include this to update the logo.
`webUrl`	string	Yes	The company website URL. Must be a valid URL including the protocol (`http://` or `https://`).

Example request body

{
  "companyBrandingName": "Updated Partner Company",
  "webUrl": "https://updated-partner-company.com"
}

Response

A successful request returns a 200 OK response with the updated branding profile details:

Field	Type	Description
`companyBrandingName`	string	The display name for branding.
`primaryLogoKey`	string	The storage key for the uploaded logo image.
`webUrl`	string	The company website URL.

Example response

{
  "message": "Branding profile updated successfully",
  "data": {
    "companyBrandingName": "Updated Partner Company",
    "primaryLogoKey": "primary/a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "webUrl": "https://updated-partner-company.com"
  }
}

Error responses

Code	Description
`400 Bad Request`	Invalid request parameters. Common causes: blank or whitespace-only branding name, invalid logo format or encoding, logo exceeds 2 MB, or invalid URL format.
`401 Unauthorized`	Authentication required.
`403 Forbidden`	User must be a Company Admin in the partner account.

​Prerequisites

​Authorization requirements

​Retrieving a branding profile

​Response

​Error responses

​Creating a branding profile

​Request

​Response

​Error responses

​Updating a branding profile

​Request

​Response

​Error responses

Prerequisites

Authorization requirements

Retrieving a branding profile

Response

Error responses

Creating a branding profile

Request

Response

Error responses

Updating a branding profile

Request

Response

Error responses