Create brand address mapping

Many businesses run more than one brand out of one support team, for example a retailer with two storefronts. In Kustomer each of these is a brand. Admins manage brands in the admin settings, and other configuration hangs off them: chat settings (colors, greeting, business hours and assistant) are set per brand, each knowledge base belongs to a brand, and the web chat SDK takes a brandId to choose which brand's widget to load. Every org starts with one brand, created when the org is registered and marked default: true. Chat uses the default brand when it starts without a brandId.

Brand fields

A brand is small: name and iconUrl are the only fields you write, and both are required when you create or update one. default tells you whether it's the org's default brand. The public API has no endpoint for deleting a brand.

Brand address mappings

A brand address mapping links an email address to a brand, so Kustomer knows which brand an address belongs to. One address can be mapped to several brands, and each brand can mark at most one of its mapped addresses with isDefault: true. Addresses are matched case-insensitively.

These endpoints behave differently from most write endpoints:

• POST /v1/brandAddresses is idempotent. Posting an address and brand pair that already exists returns the existing mapping with 200 instead of creating a duplicate. A new mapping returns 201.
• POST accepts an optional allBrands flag. When true, the address is shared across every brand, and Kustomer syncs the flag onto every mapping for that address. If you leave it out on create and another mapping for the same address is already shared, the new mapping inherits true.
• PATCH changes only isDefault and allBrands, and needs at least one of them. Setting isDefault to true moves the default from the brand's previous default address. Deleting the default mapping leaves the brand with no default; Kustomer doesn't promote another address automatically.
• Deleting all mappings for an address first checks whether the address is still connected to an email account in Kustomer. If it is, nothing is deleted and the response reports live: true. If Kustomer can't confirm either way, it deletes nothing and returns 503.

Which endpoint to use

Brand reads are available to most users. Writing brands needs brand write permission, and brand address mappings use the apps permissions. A brand can have only one default address at a time, so if two requests try to set different defaults for the same brand at once, one of them can fail with 409 Conflict. Read the mappings again and retry.