Set domain and logos

Overview

Set the custom domain and upload logo and favicon.

Use this when setting up white-label for a partner or account.

You'll need domain_name and domain_prefix (both required), and optionally a title and image files.

Branding is saved and the response is a simple success message; it doesn't include DNS records or the saved record. Point the domain's DNS at the white-label app yourself. The white-label status stays inactive until the domain is verified, so re-read it with Get branding shortly after saving rather than expecting active straight away. Each call also sets title: leave it out and it's cleared. Images you don't send are kept.

⚠️
Every call registers domain_prefix.domain_name (and its www.) as a live custom domain on our hosting, on Development as well as Production. Only call it with a domain you control and intend to serve, don't use it for smoke tests, and note that changing the domain later doesn't remove the earlier one.

Prerequisites

A bearer token. See Authentication.
A domain you control, and the subdomain to use on it.

Base URL

Environment	URL
Production	`https://production-api.shoutaboutus.com`
Development	`https://development-api.shoutaboutus.com`

Endpoint

POST /api/v1/account/white-label/update

Authentication

Partner or Account token

Acts on the account of the user behind the token; there's no company_id field.
Location accounts can't call this and get 403 with the message Sub-partner/Brand user can access this endpoint. That message names the roles that are allowed: read it as "only partner and account users can access this endpoint".

Rate limit

This endpoint has no rate limit.

Request parameters

None.

Request body

Choose the content type to match what you are sending:

You are sending	Content type
Domain and title only	`application/json`
Any image file	`multipart/form-data`

Both accept the same fields. Use multipart/form-data whenever you attach an 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.

Every image is optional; send only the ones you're changing. Note the favicon limit is 10 KB, far smaller than the 400 KB allowed for the other three.

Field	Type	Required	Description
`domain_name`	string	Yes	The custom domain, e.g. `manage-myreviews.com`. Up to 100 characters, no angle brackets. Saved in lower case.
`domain_prefix`	string	Yes	The subdomain, e.g. `acme`. Saved in lower case. `domain_prefix.domain_name` must not already be used by another account.
`title`	string	No	The browser title. Up to 100 characters, no angle brackets. Left out: cleared.
`favicon`	file	No	JPEG, PNG or ICO. At most 10 KB.
`logo`	file	No	JPEG or PNG. At most 400 KB.
`login_logo`	file	No	JPEG or PNG. At most 400 KB.
`mobile_logo`	file	No	JPEG or PNG. At most 400 KB.

Request payload

JSON, domain and title only:

{
  "domain_name": "manage-myreviews.com",
  "domain_prefix": "acme",
  "title": "My Reviews"
}

With images, send the same fields as form parts, plus the files (see Example request).

Response body

The payload is inside data.

Field	Type	Description
`status`	string	`success`.
`message`	string	`White-label data saved successfully!`.

Response payload

{
  "data": {
    "status": "success",
    "message": "White-label data saved successfully!"
  }
}

Examples

Success payload

See Response payload.

Error payload

403 Location account

{
  "message": "Forbidden",
  "status": "error",
  "errors": "Sub-partner/Brand user can access this endpoint."
}

422 Domain fields missing

{
  "message": "The domain name field is required. (and 1 more error)",
  "errors": {
    "domain_name": [
      "The domain name field is required."
    ],
    "domain_prefix": [
      "The domain prefix field is required."
    ]
  }
}

422 Subdomain already used

{
  "message": "acme.manage-myreviews.com: White URL already exists",
  "errors": {
    "domain_prefix": [
      "acme.manage-myreviews.com: White URL already exists"
    ]
  }
}

422 Image too large

{
  "message": "The favicon field must not be greater than 10 kilobytes.",
  "errors": {
    "favicon": [
      "The favicon field must not be greater than 10 kilobytes."
    ]
  }
}

Status	Meaning
`200`	The branding was saved.
`401`	The token is missing, expired or invalid.
`403`	A location account called it.
`422`	`domain_name` or `domain_prefix` is missing, the subdomain is already used by another account, or an image is too large or the wrong type.
`500`	Unexpected server error, or an image couldn't be stored.

Example request

curl --request POST \
  --url "https://production-api.shoutaboutus.com/api/v1/account/white-label/update" \
  --header 'Authorization: Bearer <bearer-token>' \
  --header 'Accept: application/json' \
  --form 'title=My Reviews' \
  --form 'domain_name=manage-myreviews.com' \
  --form 'domain_prefix=acme' \
  --form '[email protected]' \
  --form 'login_logo=@login_logo.png' \
  --form 'mobile_logo=@mobile_logo.png' \
  --form '[email protected]'