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.
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.
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 whatembed_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 withbrand_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 abrand_id:
POST /api/v1/envelopesPOST /api/v1/envelopes/one-offPOST /api/v1/envelopes/batchesPOST /api/v1/webhooksPATCH /api/v1/webhooks/{webhookId}POST /api/v1/standing-authorisations/invitations
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 batch has one brand.
brand_idonPOST /api/v1/envelopes/batchesapplies 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-offtakesbrand_idwith 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": falseand an explicitbrand_id, and that brand is recorded on the draft;POST /api/v1/envelopes/{envelopeId}/sendtakes 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 withnull, 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 explicitbrand_id. - ⚠️ The envelope resource does not say which brand it went out under.
GET /api/v1/envelopes/{envelopeId}has nobrand_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.
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.
- 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.
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 wheninclude_archivedasks 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 withbrand_is_archived. The body that adds an origin may be at most 4096 bytes.
- 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.
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
PATCH, null
removes the filter and leaving brand_id out leaves it as it was:
PATCH /api/v1/webhooks/{webhookId}
POST /api/v1/webhooks and
PATCH /api/v1/webhooks/{webhookId}.