> ## Documentation Index
> Fetch the complete documentation index at: https://docs.vumasign.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Brands

> What a signer sees, who the email says is asking, and how an envelope is given one.

export const maxEmbedOriginsPerBrand = "20";

export const brandUnknownCode = "brand_unknown";

export const brandMinimumContrast = "4.5";

export const brandHasNoEmbedOriginsCode = "brand_has_no_embed_origins";

A **brand** is how your organisation presents itself to the people who sign: a name, a logo, a
pair of colours, the name some of its emails put after “via” on the From line, and the web origins allowed to frame its
signing page. While an organisation has a live brand, every envelope it sends goes out under
exactly one, and a signer sees that brand and nothing of the others. An organisation with no brand sends
unbranded, and its webhook events carry a `brand_id` of `null`; see
[What the signer sees](#what-the-signer-sees).

An organisation has several when it sends for more than one face. The case brands were built for
is one account sending on behalf of many customers: a platform, an agency or a group whose
trading names each need their own letterhead. One API key acts for every brand; change
`brand_id` between calls and the same integration sends Customer A’s paperwork under Customer A’s
brand and Customer B’s under Customer B’s.

⚠️ **A brand is presentation and routing, not authority.** It does not partition your
organisation. A key’s [scopes](/authentication) say what it may do, never for which brand: any
key on the organisation that may read, send, void or mint a signing URL may do it for an envelope
of any brand. Do not build a permission model out of brands.

## What a brand controls

### What the signer sees

* **The signing page** shows the brand’s logo, or its name set as text when it has none, and draws
  the signer’s action buttons in the brand’s primary colour with its text colour.
* **The emails** about an envelope carry the brand, but not every part of it in every email.
  Where the From name is branded it reads *“Priya Naidoo via Acme”*: the person who sent it, then
  the brand’s **email display name**, which is the brand’s name unless you set another. The table
  is read off the rendered emails, so it is what a recipient gets:

| Email | Logo | Brand colours | “via” brand on the From line | “Powered by Vumasign”, where the plan draws it | Sender’s name on the From line, with no brand | From your sending domain |
| - | - | - | - | - | - | - |
| Invitation to sign | Yes | Yes | Yes | Yes | Yes | Yes |
| Invitation to approve | Yes | Yes | Yes | Yes | Yes | Yes |
| Reminder | Yes | Yes | Yes | Yes | Yes | Yes |
| Envelope voided | No | No | Yes | No | Yes | No |
| Completed, to each recipient | Yes | No | Yes | No | Yes | No |
| Completed, to the sender | Yes | Yes | No | No | No | No |
| Sealing failed, to the sender | Yes | No | No | No | No | No |
| Changed, please review again | No | No | No | No | No | No |

* ⚠️ **Some of those gaps are known rather than designed.** The notice asking a signer to review a
  document that changed under them carries none of the brand, although the invitation before it
  did.
* **An organisation with no brand** sends unbranded: on the signing page, its own name in place
  of a logo and the product’s colours. The From line then names the person who sent it only on the emails the table
  marks under *Sender’s name on the From line, with no brand*; the others name nobody. That is where every organisation starts, and
  it is not an error.

Whether *“Powered by Vumasign”* appears, and how many brands you may hold, depend on the plan.
Where the plan draws it, it appears on the signing page and in the emails the table above marks
under *“Powered by Vumasign”, where the plan draws it*:

| Plan | Live brands you may hold at once | “Powered by Vumasign” beneath your brand |
| - | - | - |
| Free | 1 | Yes |
| Team | No limit | No |
| Business | No limit | No |
| API | No limit | No |

The allowance counts **live** brands, the ones not archived, and is checked only when a brand is
created: archiving one frees a place. An organisation holding more than its plan allows, from
before the limit applied, keeps every one of them live, editable and sendable; it simply cannot
create another until it is back under the limit.

⚠️ **The sealed document’s signature frames carry Vumasign’s mark, whatever the brand.** The
frame is the visible face of the seal, and the seal’s certificate is issued to Vumasign, so the
mark in it names who attested the signature rather than who sent the document. See
[Sealing](/concepts/sealing).

### Who the email says is sending

A brand supplies the **name** on the From line and **never decides the address**. Which address
an email goes out from depends on the email, and on your organisation’s **Sending domains**
setting (Settings → Sending domains), where you prove a domain with DKIM. That setting belongs to
the organisation and every brand shares it.

The emails the table above marks under *From your sending domain* are the ones that use it, in one
of two ways:

* **With an organisation address** set on a proven domain, they go out from that one address,
  whoever sent them and whatever the brand.
* **Without one**, each goes out from the address of the member who sent it, when their own
  domain is proven. Two brands on one account then send from different addresses only because
  different people sent them.

Anything not covered — no proven domain for that sender, or an organisation address set but not
yet proven — goes out from Vumasign’s own sending address rather than from an address nobody
proved. An unproven organisation address does not fall back to the members’ own addresses.

⚠️ **Every email the table does not mark under *From your sending domain* goes out from
Vumasign’s own sending address**, whatever Sending domains says. Its From *name* is still branded
where the table marks it under *“via” brand on the From line*.

**A brand has no sending domain of its own.** Choosing one changes the name after “via”, never the
address beside it.

### Where its signing page may be framed

A brand’s **embedding origins** are the web origins allowed to frame a signing page for an
envelope sent under it, at most {maxEmbedOriginsPerBrand} per brand. They live on the brand
rather than on the API key because each brand is one customer, and each customer embeds on their
own domain. [Embedded signing](/guides/embedded-signing) has the rules for writing them.

⚠️ They are a clickjacking defence for the signer, **not an access boundary** for you, and they
are what <code>{brandHasNoEmbedOriginsCode}</code> is about: an envelope with an embedded recipient is refused
at creation, and a signing URL when it is minted, if the brand the envelope goes out under has
none registered, or if it goes out under no brand at all, because nothing could reach that
recipient.

### Which webhook endpoints hear about it

A webhook endpoint may be filtered to one brand with `brand_id`. Every event carries the
`brand_id` of the brand its envelope went out under, filtered or not, so a single unfiltered
endpoint with a `switch` on that field is a complete integration; you do not need an endpoint per
brand. An envelope sent with no brand reaches only the endpoints with no filter. See
[Webhooks](/guides/webhooks).

⚠️ **The filter is routing, not isolation.** It decides which events are posted to which URL. It
does not stop any key on the organisation reading any envelope.

## Choosing a brand from the API

These requests take a `brand_id`:

* [`POST /api/v1/envelopes`](/api-reference/create-envelope)
* [`POST /api/v1/envelopes/batches`](/api-reference/create-envelope-batch)
* [`POST /api/v1/webhooks`](/api-reference/create-webhook)
* [`PATCH /api/v1/webhooks/{webhookId}`](/api-reference/update-webhook)

On an envelope create, `brand_id` is optional:

* **Omit it**, or send `null`, and the envelope goes out under the organisation’s
  [default brand](#the-default-brand) when it is sent, or unbranded if the organisation has none.
* **Name a brand**, and it goes out under that one, unless it is archived before the envelope is
  sent (see [Frozen at send](#frozen-at-send)). Copy the id from **Settings → Brands**, where every
  brand shows its Brand ID with a copy button.
* ⚠️ **An id that names no live brand of your organisation is refused with <code>{brandUnknownCode}</code>,
  not ignored.** That includes a brand that has been archived and one belonging to another
  account. The branding is frozen when the envelope is sent, so a wrong constant in your
  configuration would otherwise put the wrong letterhead on everything you send, permanently.

```json POST /api/v1/envelopes theme={null}
{
  "template_id": "9f2a6c1e-4b7d-4e2a-8c3f-1d5e7a9b0c24",
  "recipients": [
    { "role": "Tenant", "name": "Ada Lovelace", "email": "ada@example.com" }
  ],
  "brand_id": "3f6c2a1e-8d4b-4c7a-9e21-5b0d7f9a1c42",
  "send": true
}
```

A few things follow from where the field is, and where it is not:

* **A batch has one brand.** `brand_id` on
  [`POST /api/v1/envelopes/batches`](/api-reference/create-envelope-batch) applies to every
  envelope in it. Two brands means two batches.
* **A one-off envelope cannot choose.**
  [`POST /api/v1/envelopes/one-off`](/api-reference/create-one-off-envelope) has no `brand_id`,
  so it records no brand and goes out under the [default brand](#the-default-brand) when it is sent,
  or unbranded if there is none.
* **A draft keeps a brand only if its create named one.** Create with `"send": false` and an
  explicit `brand_id`, and that brand is recorded on the draft;
  [`POST /api/v1/envelopes/{envelopeId}/send`](/api-reference/send-envelope) takes no body and
  sends it under that brand. Sending the same draft from the dashboard does too: the send screen
  starts on the draft’s brand, and the draft goes out under another only if the person sending it
  picks one there.
* ⚠️ **A draft created without a `brand_id`, or with `null`, records no brand.** It goes out
  under the [default brand](#the-default-brand) **when it is sent**, not when it was created, or
  unbranded if there is none then. If the
  default changes in between, the draft follows it. When the letterhead matters, pass an explicit
  `brand_id`.
* ⚠️ **The envelope resource does not say which brand it went out under.**
  [`GET /api/v1/envelopes/{envelopeId}`](/api-reference/get-envelope) has no `brand_id`. Every
  webhook event carries it; otherwise, keep the id you sent.

## The default brand

**When nothing chooses a brand, an envelope goes out under the organisation’s default brand as it
stands when the envelope is sent, or unbranded if the organisation has no live brand at that
moment.** Every mention of the default on this page means that.

* A **brand created while the organisation has no live brand becomes its default**, without
  asking.
* While the organisation has live brands, **exactly one** of them is the default. **Make default**
  on Settings → Brands changes which.
* **Archiving the default promotes another brand** in its place, so an organisation with brands
  always has a default. Archiving the only brand leaves the organisation unbranded, where it
  started.
* When the organisation has more than one brand, the dashboard’s send screen offers a choice,
  starting on the brand the draft records, or on the default when it records none or that brand
  has been archived. With one brand it never asks.

Changing the default changes what the **next** envelope is sent under when nobody chose,
including a draft already created without a `brand_id` and not yet sent. It does not touch an
envelope already sent.

## Frozen at send

When an envelope is sent, the brand is **frozen** onto it: the brand it went out under, and a
snapshot of every setting the table under [Creating and managing brands](#creating-and-managing-brands)
marks under *Frozen onto the envelope at send*, together with whether the send carried
*“Powered by Vumasign”*. The database refuses any later change to either.

So after an envelope is sent:

* **Editing the brand changes nothing a signer of it sees.** A new logo, a new colour or a new name
  applies to envelopes sent afterwards. A reminder sent weeks later looks like the invitation it
  follows.
* **Archiving the brand changes nothing either.** The envelope keeps its reference and its
  snapshot.
* **Changing plan changes nothing.** An envelope sent with *“Powered by Vumasign”* keeps it after
  you upgrade.

⚠️ **The embedding origins are read live**, and they are the one exception. They decide who may
frame a signing page *now*, so they are not part of the snapshot, and a change applies to envelopes
already sent under that brand. When it applies depends on which way it goes, because a signing URL
copies the list when it is **minted** and the list is read again when the URL is **opened**:

* **An origin you add** applies to signing URLs minted after you add it. A URL minted before
  carries the old list and will not load on the new origin: mint a new one.
* **An origin you remove** stops applying when a URL is opened. The signing session it starts is
  framed only for the origins still registered, and a URL whose brand has none left is refused.
  A signing session already open keeps the origins it opened with until it ends.

⚠️ **The brand is settled at send, not at create.** A draft created under a brand that is
archived before the draft is sent goes out under the organisation’s default instead, or unbranded
if no live brand is left, and nothing refuses the send. If you archive brands, send the drafts that name them first.

## Creating and managing brands

Brands are made and managed in the dashboard, at **Settings → Brands**, by any member of the
organisation. **The API has no endpoint that creates, lists, edits or archives a brand.** An
integration reads its brand ids from that screen once and keeps them as configuration.

Each brand has these settings, named as the settings screen names them:

| Setting | Frozen onto the envelope at send |
| - | - |
| Brand name | Yes |
| Primary colour | Yes |
| Text on that colour | Yes |
| Email display name | Yes |
| Logo | Yes |
| Embedding origins | No, read live |

* The **brand name** is shown on the signing page when there is no logo, and is the email display
  name unless one is set. It must be unique among the organisation’s live brands.
* The **primary colour** and the **text on that colour** draw the signer’s action buttons. The
  pair must reach a contrast of at least {brandMinimumContrast}:1, so the label stays readable.
* The **email display name** is the name after “via” on the From line, on the emails the table
  marks under *“via” brand on the From line*. Empty means the brand name.
* The **logo** is shown on the signing page and in the emails the table marks under *Logo*.
* The **embedding origins** are where this brand’s signing page may be framed. See
  [Embedded signing](/guides/embedded-signing).

Which brand is the **default** is not one of those settings: it is chosen on the list of brands,
and it is about the organisation today rather than about any one envelope, so it is never frozen.
See [The default brand](#the-default-brand).

A brand is **archived, not deleted**. It leaves every list and picker, its name is free to use
again, and every envelope sent under it keeps its reference and its snapshot.

## Refusals

Every refusal named for a brand, from the API’s own list of error codes. The full list is on
[Errors](/errors).

| Code | HTTP | Retry? | What it means |
| - | - | - | - |
| `webhook_brand_unknown` | 422 | no | `brand_id` names no brand of this organisation. ⚠️ 422 and not 404 because you asked for a WEBHOOK — the brand is a property of the body that does not fit. Send `null` to receive every envelope in the organisation. On registration, omitting it means the same; on a `PATCH`, omitting it leaves the endpoint’s filter as it was. |
| `brand_has_no_embed_origins` | 422 | no | The brand has no embedding origins registered, so a signing URL for it could not be framed by anything — and an embedded recipient is never emailed, so they would be unreachable. Register the domains you embed on against that brand in Settings; they must be bare origins (`https://example.com`, no trailing slash and no path). ⚠️ THE BRAND IS THE ONE THE ENVELOPE GOES OUT UNDER — the `brand_id` you sent, or the organisation’s default when you sent none. It is NOT always the default: registering an origin against the default while sending under another brand is the mistake this refusal most often means. |
| `brand_unknown` | 422 | no | `brand_id` names no live brand of your organisation — it may belong to another account, or have been archived. Read the ids from Settings, or omit the field to send under the default. ⚠️ IT IS REFUSED RATHER THAN IGNORED because the branding an envelope went out under is frozen the moment it is sent: a wrong constant would put somebody else’s letterhead on every envelope you send, permanently, and nothing else would say so. (The product’s own send screen falls through to the default instead, because there the id came from a list a person was shown rather than from a program.) |

## Filtering a webhook endpoint by brand

Register an endpoint that hears only one brand’s envelopes:

```json POST /api/v1/webhooks theme={null} theme={null}
{
  "url": "https://api.example.com/hooks/vumasign",
  "events": [
    "envelope.completed"
  ],
  "brand_id": "3f6c2a1e-8d4b-4c7a-9e21-5b0d7f9a1c42"
}
```

Remove the filter later, so it hears every envelope in the organisation. On a `PATCH`, `null`
removes the filter and leaving `brand_id` out leaves it as it was:

```json PATCH /api/v1/webhooks/{webhookId} theme={null}
{
  "brand_id": null
}
```

Unlike an envelope create, a webhook filter accepts an archived brand’s id, since envelopes
already sent under it go on producing events. See
[`POST /api/v1/webhooks`](/api-reference/create-webhook) and
[`PATCH /api/v1/webhooks/{webhookId}`](/api-reference/update-webhook).