Set colours and theme

Overview

Set the colours and theme options used across the branded experience.

Use this to match your brand. A second endpoint, Set colours and theme (options + logo), does the same with slightly different inputs; use whichever fits.

You'll need the theme values.

The theme is saved and applied. The response has the saved theme plus the account's white-label record, with every image field as a full URL (or null where unset). Uploading a logo also creates the account's white-label record if it doesn't exist yet, which is why white_label can come back with most fields missing on a first upload.

Prerequisites

• A bearer token. See Authentication.
• The company_id of the account you're theming, inside your own account tree.
• Your user id (user_id).
• To upload a logo: a JPEG or PNG no larger than 400 KB.

Base URL

Endpoint

POST /api/v1/account/white-label/theme/save

Authentication

Partner or Account token

• company_id must be inside your own account tree. A Partner token can theme any account under the partner; an Account token only its own account.
• user_id is recorded as who saved the theme; send your own user id.
• An account outside your tree, or one that doesn't exist, is rejected with 422.

Rate limit

This endpoint has no rate limit.

Request parameters

None.

Request body

Choose the content type to match what you are sending:

Both accept the same fields. Use multipart/form-data whenever you attach logo_image, because a file can't travel in a JSON body. Send each field as its own form part and let curl set the boundary; don't set Content-Type yourself.

Request payload

JSON, theme options only:

{
  "user_id": 3011,
  "company_id": 5994,
  "theme_options": "{\"mode\":\"system\",\"primaryColor\":\"#f1874c\"}"
}

With a logo, send the same fields as form parts, plus logo_image (see Example request).

Response body

The payload is inside data.

Response payload

{
  "data": {
    "status": "success",
    "message": "Theme options saved successfully.",
    "data": {
      "company_id": 5994,
      "user_id": 3011,
      "theme_options": "{\"mode\":\"system\",\"primaryColor\":\"#f1874c\"}",
      "updated_at": "2026-09-28T14:54:45.000000Z",
      "created_at": "2026-09-28T14:54:45.000000Z",
      "id": 5
    },
    "white_label": {
      "company_id": 5994,
      "logo": "https://d2ny6zb7otrnhl.cloudfront.net/white-label/logo/evjRaIHr6bWR4gsfk2vAaLUI49XMAcKB6lEFCIZA.png",
      "id": 8,
      "login_logo": null,
      "mobile_logo": null,
      "favicon": null
    }
  }
}

Examples

Success payload

See Response payload.

Error payload

422 Required fields missing

{
  "message": "The user id field is required. (and 2 more errors)",
  "errors": {
    "user_id": [
      "The user id field is required."
    ],
    "company_id": [
      "The company id field is required."
    ],
    "theme_options": [
      "The theme options field is required."
    ]
  }
}

422 Account outside your tree

{
  "message": "The selected company id does not belong to your company hierarchy.",
  "errors": {
    "company_id": [
      "The selected company id does not belong to your company hierarchy."
    ]
  }
}

422 Logo too large

{
  "message": "The logo image field must not be greater than 400 kilobytes.",
  "errors": {
    "logo_image": [
      "The logo image field must not be greater than 400 kilobytes."
    ]
  }
}

Example request

curl --request POST \
  --url "https://production-api.shoutaboutus.com/api/v1/account/white-label/theme/save" \
  --header 'Authorization: Bearer <bearer-token>' \
  --header 'Accept: application/json' \
  --form 'user_id=3011' \
  --form 'company_id=5994' \
  --form 'theme_options={"mode":"system","primaryColor":"#f1874c"}' \
  --form 'logo_image=@logo_image.png'