Brands

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. 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 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.

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 20 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 has the rules for writing them. ⚠️ They are a clickjacking defence for the signer, not an access boundary for you, and they are what brand_has_no_embed_origins 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. ⚠️ 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:

On an envelope create, brand_id is optional:

Omit it, or send null, and the envelope goes out under the organisation’s 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). 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 brand_unknown, 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.

POST /api/v1/envelopes

{
  "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 applies to every envelope in it. Two brands means two batches.
A one-off envelope cannot choose. POST /api/v1/envelopes/one-off has no brand_id, so it records no brand and goes out under 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 takes no body and sends it under that brand. ⚠️ Sending the same draft from the dashboard does not: the send screen chooses a brand itself, starting on the default rather than on the draft’s, and what it chooses wins.
⚠️ A draft created without a brand_id, or with null, records no brand. It goes out under 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} 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 default. 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 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 4.5: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.

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. 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.

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

POST /api/v1/webhooks

{
  "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:

PATCH /api/v1/webhooks/{webhookId}

{
  "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 and PATCH /api/v1/webhooks/{webhookId}.

Get started

Concepts

Guides

What a brand controls

What the signer sees

Who the email says is sending

Where its signing page may be framed

Which webhook endpoints hear about it

Choosing a brand from the API

The default brand

Frozen at send

Creating and managing brands

Refusals

Filtering a webhook endpoint by brand

​What a brand controls

​What the signer sees

​Who the email says is sending

​Where its signing page may be framed

​Which webhook endpoints hear about it

​Choosing a brand from the API

​The default brand

​Frozen at send

​Creating and managing brands

​Refusals

​Filtering a webhook endpoint by brand

What a brand controls

What the signer sees

Who the email says is sending

Where its signing page may be framed

Which webhook endpoints hear about it

Choosing a brand from the API

The default brand

Frozen at send

Creating and managing brands

Refusals

Filtering a webhook endpoint by brand