Skip to main content
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 identity check’s screens, on the computer and on the phone, wear the brand the same way. Where they say who is asking, they name the brand by its email display name, as the emails to your signers do, and so does the WhatsApp message or text that sends the check’s link to the signer’s phone. Your organisation’s own name appears there only on an envelope sent without a brand.
  • The emails about an envelope carry the brand’s logo above the message where the table marks them under Logo, or the brand’s email display name in dark text when it has no logo. Apart from the logo, an email about an envelope carries no image. Its primary colour and text colour draw the button where it marks them under Brand colours, which are the ones with a button; the colour is used nowhere else in an email. The emails the table marks under Goes to as going to your signers also carry the brand on the From line, which 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. A member whose account has no name of its own is shown by your organisation’s name there and in the opening line, never by their address, and when that name is the brand’s display name it appears once rather than as “Acme via Acme”. Emails to you rather than to your signers, which the table marks under Goes to, show the brand the same way but keep Vumasign’s own From line, because they are Vumasign writing to its customer. The table is read off the rendered emails, so it is what a recipient gets:
  • An organisation with no brand sends unbranded: its own name in place of a logo on the signing page and above the message in its emails, 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, or your organisation for a member with no name; 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: 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 rule is who the email is written to. Once a domain is proven, the emails the table marks under Goes to as going to your signers — anyone you send an envelope to, whether they sign, approve or are copied in — go out from it. Emails to you as the sender, and emails about your account rather than about an envelope, come from Vumasign. The product’s code records which of those a kind of email is written to, and a new one cannot be added without saying. 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. ⚠️ An 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. They are what embed_origin_not_registered is about: a signing URL minted with an embed_origin that the brand has not registered is refused rather than handed back, because the browser would refuse to frame it. 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
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. The dashboard’s Send in bulk asks the same question under Send as when the organisation has more than one brand, and every envelope it sends goes out under the brand chosen.
  • A one-off envelope chooses the same way. POST /api/v1/envelopes/one-off takes brand_id with the same rules, and records it on the envelope. Without one it 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 too: the Send step 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 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 step 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 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. An email about the envelope sent weeks later looks like the first one.
  • 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 the organisation’s owners and admins. Other members see the brands and their ids there, and cannot change them. The API has no endpoint that creates, edits or archives a brand. It can read them, and add or remove a brand’s embedding origins one at a time:
  • Reading needs brands:read. Every full-access key holds it, and so does every read-only key, including one created before brands could be read over the API: a read-only key holds every read scope, those added later too, with no new key needed. An integration can list its brands to find their ids rather than copying them from the screen. Archived brands are listed only when include_archived asks for them. A brand’s logo is given as a public URL, the same one its signing pages and emails load.
  • Changing embedding origins needs brands:write, which a full-access key does not hold: a key must be given it by name, and only a live key can be. An owner or admin adds it to an existing key under Settings → API keys with Edit permissions; no new key is needed. A test key is refused, because a brand serves live sends too. ⚠️ Every origin it adds may frame the signing pages of that brand’s envelopes. Adding an origin that is already there, or removing one that is not, succeeds and changes nothing, so a retry is safe. An archived brand is refused with brand_is_archived. The body that adds an origin may be at most 4096 bytes.
Each brand has these settings, named as the settings screen names them:
  • 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. In an email, that pair on the button is the only place the colour appears.
  • 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, and the name above the message, in place of a logo, when the brand has none. 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.

Filtering a webhook endpoint by brand

Register an endpoint that hears only one brand’s envelopes:
POST /api/v1/webhooks
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}
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}. Standing authorisations: a grantor’s mandate covers documents sent under one brand, and records that brand’s name, email display name and logo as the grantor saw them.