Guides

Custom Colors Data Structure

Suggest Edits

Overview

This document describes the exact structure required for POST requests to the custom colors API endpoint when using Worklio white-label application with prebuilded components.

If you are building your own UI and using our API endpoints directly, you can choose whatever data structure works best for your implementation.

API Endpoint

POST /wep/brand/custom-colors
POST /wep/companies/{companyId}/brand/custom-colors

Request Structure

Wrapper Object

interface CustomColorsRequest {
  /** Brand colors data as JSON string */
  data: string;
}

Data Field Content

The data field contains a JSON string with the following structure:

interface CustomColorsData {
  /** Skin preset name, 'worklio' is default. If 'worklio' is used, all other properties are ignored */
  skin?: 'worklio' | 'custom';

  /** Primary accent color (OpenColor name like 'blue', 'red' or hex like '#1c49fe') */
  primary?: string;

  /** Secondary accent color ('auto', 'none', OpenColor name, or hex color) */
  secondary?: 'auto' | 'none' | string;

  /** Array of up to 5 custom avatar colors. Default is ["#748ffc","#66d9e8","#94d82d","#ffd43b","#f06595"] */
  avatar?: string[];

  /** Background image name. Default is 'gradient'. Please note that in iframes this property is ignored and always uses 'none' */
  background?: 'none' | 'gradient' | 'waves';

  /** Application background color. Please note that in iframes this property is ignored and always uses 'white' */
  backgroundColor?: 'gray' | 'white';

  /** Menu background color ('auto', 'inherit', 'primary', OpenColor name, or hex color) */
  menuColor?: 'auto' | 'inherit' | 'primary' | string;

  /** UI element shape preference. Default is 'circle' */
  preferredShape?: 'circle' | 'round' | 'sharp';

  /** Pre-calculated brand colors (optional) */
  calculatedColors?: CalculatedBrandColors;
}

Example Requests

Basic Color Configuration

{
  "data": "{\"skin\":\"custom\", \"primary\":\"#1c49fe\",\"secondary\":\"none\",\"background\":\"none\",\"backgroundColor\":\"white\"}"
}

Complete Configuration with Custom Avatar Colors

{
  "data": "{\"skin\":\"custom\", \"primary\":\"#1c49fe\",\"secondary\":\"none\",\"background\":\"none\",\"backgroundColor\":\"white\",\"avatar\":[\"#748ffc\",\"#66d9e8\",\"#94d82d\",\"#ffd43b\",\"#f06595\"]}"
}

Calculated Colors Structure

The purpose of including pre-calculated colors is to speed up client application rendering.

⚠️

Important

The calculated colors structure may change in future versions as the color calculation algorithm evolves. Always check the current version before including these values. If there is a version mismatch with the current version, it is ignored.

Current Version: "20250425"

interface CalculatedBrandColors {
  /** Color calculation version - Current: "20250425" */
  version: string;

  /** Source colors used for calculation */
  from: {
    primary?: string;
    secondary?: string;
    menuColor?: string;
  };

  /** Primary color palette (10 shades) */
  primaryPalette: string[];

  /** Secondary color palette (10 shades) */
  secondaryPalette: string[];

  /** Dark theme colors */
  darkColors: {
    activeSurface: string;
    activeBackground: string;
    primary: string;
    primarySurface: string;
    secondary: string;
    secondarySurface: string;
    svgBackground1: string;
    menuSurface: string;
    menuHoverSurface: string;
    primaryTagSurface: string;
    primaryTagText: string;
    textOnPrimarySurface: string;
    textOnSecondarySurface: string;
  };

  /** Light theme colors */
  lightColors: {
    activeSurface: string;
    activeBackground: string;
    primary: string;
    primarySurface: string;
    secondary: string;
    secondarySurface: string;
    svgBackground1: string;
    primaryTagSurface: string;
    primaryTagText: string;
    textOnPrimarySurface: string;
    textOnSecondarySurface: string;
  };

  /** Menu color information */
  menu: {
    isGrayscale: boolean;
    isColored: boolean;
    isBlackText: boolean;
    isWhiteText: boolean;
    colors: Record<string, string>;
  };
}

Color Value Formats

Color fields accept multiple formats:

Predefined Color Names (OpenColor)

The following OpenColor names are supported:

  • "red"
  • "pink"
  • "grape"
  • "violet"
  • "indigo"
  • "blue"
  • "cyan"
  • "teal"
  • "green"
  • "lime"
  • "yellow"
  • "orange"

Hex Colors

  • "#1c49fe" (6-digit hex)
  • "#fff" (3-digit hex, expanded to #ffffff)

Special Values

  • "auto" - Automatically calculated based on primary color (for secondary)
  • "none" - Uses the same color as primary (for secondary)
  • "inherit" - Inherits foreground color (for menuColor)
  • "primary" - Uses the primary color (for menuColor)
  • "gray" - Uses theme-appropriate gray (for backgroundColor)
  • "white" - Uses foreground color (for backgroundColor)

Updated 3 days ago