What is fixed at send
Fixed from says when each one stops changing. Most are fixed at send; the few marked
Creation can never change at all, even while the envelope is still a draft.
These are refused by the database, not by a screen, so there is no route around them. A few more
things do not change after send, for different reasons:
- The fields. Editing a template does not change an envelope already sent from it. The envelope carries its own copy of the layout, made when it was created, and the sender cannot edit the fields of a sent envelope. The code does contain an amendment that would copy a changed template onto envelopes still in flight, discarding the answers typed so far and refusing once anybody has signed, approved or declined. Nothing in the product calls it, so no customer can reach it, in the dashboard or through the API.
- The deadline, except later.
expires_atis set when the envelope is created, onPOST /api/v1/envelopesand the other create operations, or in the dashboard when it is sent. After send it can only be moved later, while it is still running: see Deadlines. It can never be moved earlier or removed. - The title, and who created it.
title, and the person the envelope records as its creator (senderonPOST /api/v1/envelopes/one-off, otherwise whoever created the API key, or whoever made it in the dashboard), are set when the envelope is created. Nothing in the API or the dashboard changes either afterwards, even on a draft. The creator is not always the person the emails name: see Who the emails name. - The covering note. The note sent with the invitations is written when the envelope is created or when it is sent, and nothing changes it after send. A reminder or a resend repeats it.
- Each recipient’s key. A recipient’s
external_refnever changes on that recipient. Anybody who takes their place after send, by a correction or a delegation, is a new recipient with a newidand starts without one. On a draft, saving the recipients in the dashboard keeps each one whose address is unchanged, with itsid, its key, whether it is embedded and anything you prefilled for it; an address differs only if its part before the @ differs, or its domain differs other than in capitals. A recipient given a new address becomes a new recipient, which keeps only whether it is embedded.
Who can change what
“The sender” here is anybody in your organisation signed in to the dashboard: nothing limits these to the person who sent the envelope. “The recipient” acts from the signing page, emailed or embedded in yours.
When a replacement recipient, or anybody else, later signs or approves,
recipient.completed
fires as usual.
Voiding
POST /api/v1/envelopes/{envelopeId}/void withdraws an envelope
that is out for signature, with a reason somebody will read later. The sender can do the same from
the dashboard. Either way every outstanding signing link is revoked, the envelope becomes voided,
and envelope.voided fires. Nothing is deleted: signatures already collected and the evidence
behind them stay where they are. A draft, or an envelope that has already finished, is refused as
envelope_not_sent. A draft has nothing to withdraw: discard it instead with
DELETE /api/v1/envelopes/{envelopeId}, which deletes it (see
Discarding a draft).
A test key voids only an envelope a test key created: naming one made in the dashboard or
with a live key is refused test_key_cannot_void, and nothing is voided.
⚠️ A void through the API emails nobody. A void from the dashboard writes to say the document
has been withdrawn, without saying who withdrew it, to every recipient whose status is sent, opened, signed or approved: everybody
who has been invited and has not yet acted, and everybody who had already signed or approved.
Three kinds of recipient are never written to: embedded recipients, anybody whose turn had not come, and
cc recipients. The last two were sent nothing before the void, so they hear nothing about it. The API does not write to anybody. If your integration voids, tell the people
who were signing yourself; a signer who follows an old link is told the envelope was withdrawn,
but only if they click it.
The envelope’s history records the void and its reason, attributed to the API key when your
integration made it and to the person when the sender did.
Correcting a recipient
The sender can correct the name or address of a recipient whose status is pending, sent or opened, while the envelope is still out for signature, from the envelope in the dashboard. Acc recipient
can be corrected too. This is dashboard only.
Nothing is edited in place. The original recipient keeps the address that was actually invited
and is retired; a new recipient, with a new id, takes the same role and the same position. The
sender gives a reason, and the certificate of completion prints it beside the handover. The
replacement is invited when its turn comes: at once if its step is open, later if somebody in an
earlier step has not finished. A cc replacement is not
asked for anything, and a correction of an embedded recipient is embedded too, so it is never emailed.
⚠️ Anything the original recipient had filled in but not signed is lost: saved answers belong to
the recipient who typed them, and the replacement starts without them. Correcting somebody who has
already opened the document and started throws that work away.
No webhook fires. The envelope’s history shows the correction.
Delegation
A recipient who signs or approves and is not the right person can hand the document to somebody else, from the signing page: a name, an address and a reason. This is signer only; neither the sender nor the API can do it on their behalf. It is final. Their link stops working at once, anything they had filled in but not signed is lost exactly as in a correction, and they stay on the record as the person originally asked. The replacement is created exactly as for a correction, and the certificate of completion prints the reason.recipient.delegated fires, carrying the delegator as recipient_id, the new
recipient as delegate_recipient_id, and delegate_embedded, which says how the new recipient is
reached. It carries ids only; read the new recipient’s name and address from the envelope.
The delegate of an embedded recipient is emailed. Your page has a seat for the person you
authenticated, not for somebody they name, so by default the replacement is an ordinary recipient,
not embedded: invited by email with a signing link, reminded and sent the completed copy like
anybody else. If you create the recipient with delegates_stay_embedded set, the replacement is
embedded instead: nobody emails them, and they sign only once you mint them a URL. See
Embedded signing.
If the recipient was signing in your page, the iframe also posts delegated: take
the iframe down.
Finding the replacement
After a correction or a delegation,GET /api/v1/envelopes/{envelopeId} still lists the original
recipient, with one of these statuses:
The response carries no link from a retired recipient to the one who replaced them; for a
delegation,
recipient.delegated is that link. Outside a
cc role or a signing group, a role has one person at a time, so the replacement is the recipient with the same
role whose status is not one of the above. Several people can share a cc role, and there the
API cannot tell you who replaced whom.
The replacement starts with the recipient’s external_ref set to null, and no endpoint sets
one: your key named a person, and the replacement is somebody else. From here on, match them by
id. The envelope’s own reference is untouched: it is fixed from creation, and replacing a
recipient does not change it.
⚠️ A correction fires no webhook, so the first you may hear of a corrected recipient is a
recipient.completed whose recipient_id you have never seen. Treat an unknown recipient as a
reason to re-read the envelope, not as an error.
Fresh links
A signing link is a single credential, and only a digest of it is stored, so the same link can never be sent twice. Every way of emailing a recipient again issues a new link, and the previous one stops working. A recipient holding an older email will find its link dead; the newest email is the one that works. Embedded URLs are the exception, below. When signing is in steps, a recipient whose turn has not come has no link, and none of these gives them one early. Should one ever reach them, the signing page does not open the document, to read or to sign: it tells them it is not their turn yet. When their turn does come an emailed recipient is sent a new link, and the stray one stops working.- Resending. The sender can send a fresh invitation to an emailed recipient who signs or
approves and whose status is sent or opened, while the envelope is still out for
signature, from the dashboard. A
ccrecipient holds no link, so there is none to resend; a recipient whose turn has not come has not been invited yet; and an embedded recipient is never emailed. It is the same recipient with a new link, so anything they had saved is kept. This is dashboard only. - Reminders. Every organisation starts with a reminder every 3 days, at
most 3 times, including one that existed before reminders were on by default
and had no cadence set. An organisation’s owners and admins can change the
cadence, or turn reminders off, in the dashboard’s settings. When one is set, every emailed recipient who signs or approves and has not yet acted is reminded on that
cadence, up to the number of times you chose, and each reminder carries a fresh link. Embedded
and
ccrecipients are never reminded, and nobody is reminded once the deadline has passed. There is no per-envelope setting and nothing in the API. - A link that has expired. A recipient whose emailed link has expired can ask the signing page for a new one, which goes to the address that was invited. This is signer only, it is the same reissue as the sender’s resend, and it is for emailed recipients only: an embedded signer whose session has expired is sent back to your page instead.
- Embedded URLs. Mint another with
POST /api/v1/envelopes/{envelopeId}/recipients/{recipientId}/signing-url. Minting does not cancel an earlier URL: each one stays usable until it is opened, the envelope’s deadline passes or its 10 minutes run out, whichever comes first. Opening a URL starts a session, cut short by the deadline in the same way, and ends any session an earlier URL began, so the URL opened last is the one that works.
Declines
Declining is signer only. A decline ends the envelope: it becomesdeclined, nobody else can sign,
and envelope.declined fires. The member who sent the envelope is emailed, with the decliner’s
name and reason, unless they have since left your organisation or the envelope’s completion_delivery
is integrator: then your integration is the one telling people what happened, and we
email nobody, exactly as for the completed copies. Unless one of those two applies, every other recipient
whose status is sent, opened, signed or approved is also emailed that the document won’t be completed because someone
declined it. That email names neither the person who declined nor their reason, and it goes to nobody who
was never sent anything: not a recipient whose turn had not come, not a cc recipient, and not
an embedded signer. The webhook is how your integration finds out. It is terminal, and the only way forward
is a new envelope.
The one exception is a member of a signing group whose other members can still
act: their decline is recorded, the envelope stays open, and no webhook fires. The API creates no
such group.
A cc recipient is never given a signing link, so cannot decline. Were one to decline, it would be
recorded and would not end the envelope.
Signing groups
The model has one more way to retire a recipient: a signing group, where any one of several people may fill a role. The first to sign or approve wins, and the others are retired asgroup_resolved
with their links revoked. recipient.completed fires once, for the member who acted, and never for
the members retired. A member who declines does not end the envelope while another member can
still sign.
Nothing you can call creates a signing group. The API refuses two recipients naming one signing
role as recipient_role_duplicated, and the dashboard refuses the same roster at send unless its
people are one group. The dashboard’s editor does not make a group either: a group already on a
template is filled with its people at send, and the editor can turn it back into one person. You
will not see group_resolved on an envelope you created and sent
through the API; it is described here because the reference names it.
Deadlines
An envelope has a deadline only if one was set:expires_at on
POST /api/v1/envelopes, or Deadline in the dashboard’s Send
dialog, where a date is taken to end at the close of that day in South Africa. A deadline must be
at least 1 hour away and at most 365 days away.
POST /api/v1/envelopes/{envelopeId}/extend gives an
envelope that is out for signature a later deadline, and the sender can do the same from the
dashboard. The envelope’s history records it, with both deadlines. Nobody is emailed and no
webhook fires; read the new expires_at from the response or from the envelope.
- No link is replaced. Each signing link keeps the life it was given when it was sent, which was never longer than the old deadline. A recipient whose link stops working at the old deadline can ask for a fresh one from the signing page, and that one runs to the new deadline, as do the links in reminders.
- Later only. A deadline that is not later than the current one, or a request for an envelope
with no deadline, is refused as
deadline_not_extendable. - A year from sending, in all. The new deadline must be at least 1 hour away and no
more than 365 days after the envelope was sent, however many times it is extended. One
outside those bounds is refused as
invalid_request. - A test key extends only a sandbox envelope. A test key naming an envelope that a test key did
not create is refused as
test_key_cannot_extend. - Only while it runs. A draft, a finished envelope, and an envelope whose deadline has already
passed are refused as
envelope_not_sent, even before the sweep below marks itexpired.
Expiry
When an envelope’sexpires_at passes before everybody has acted, a scheduled sweep marks it
expired, revokes every outstanding link, and envelope.expired fires. Nobody acted to produce
it. The member who sent the envelope is emailed, with who had signed or approved and who had not,
unless they have since left your organisation or its completion_delivery is
integrator, as for a decline; no recipient is emailed, so the webhook is how your
integration finds out. It is terminal, and a partly
signed envelope expires like any other: the signatures stay on it, and the only way forward is a
new envelope.
The sweep runs on a schedule, not at the instant of the deadline. In between, the envelope can
still show an open status, but nobody can sign it: every signing link was capped at the deadline
when it was issued, and minting an embedded URL is refused as envelope_not_sent.
Who the emails name
Every email a recipient receives about an envelope names one member of your organisation as the person asking: the member who sent it. The one exception is a code a recipient asks for after that member has left, described below. Who that is gets recorded at the moment of sending and never changes, so the invitations, every reminder, a fresh link, a resend, the invitation to a corrected recipient or to somebody a recipient handed the document to, the notice that it was withdrawn and the completed copies all name the same person, and a reply to any of them reaches that person.- From the dashboard, it is whoever pressed Send, who may not be the member who created the draft. A colleague who later resends it, corrects a recipient or voids it is recorded in the envelope’s history as having done so, but the emails still name the member who sent it. The notice of a void says the document has been withdrawn and that it came from that member; it does not say who withdrew it.
- Through the API, it is the envelope’s creator: the one-off’s
sender, or otherwise whoever created the API key that created it. An API key is not a person, soPOST /api/v1/envelopes/{envelopeId}/sendsends a draft in its creator’s name whichever key calls it, exactly as sending it when it is created would have.
envelope_sender_removed.
For an envelope already out, the reminders, resends, corrections, delegations, fresh links, the
invitation to the next step’s signers and the completed copies all
stop, and a void from the dashboard still withdraws it but writes to nobody. A recipient whose
handover would need an invitation emailed is told the document cannot be passed on, and it stays
with them. Void it and send a new one, and tell the recipients yourself.
The signing page does not name the member who sent it: it names your organisation, under the brand
the envelope was sent with. So a recipient whose link still works can open the document and act on
it after that member has left. A recipient asked for a code can
still get one, because they cannot open the document without it: the code screen, and the email or text
that carries the code, name your organisation instead of the member, and a reply to the email does not go to them. It goes
out from your organisation address if one is set on a proven domain, and from Vumasign’s own sending
address otherwise.
The two emails your own organisation receives go to the member who sent it too, not to the member
who created the envelope: the notice that it is complete, with the executed copy, and the notice
if it could not be sealed. If that member has left, nobody is written to, and nobody else is
written to instead: the envelope’s history records that the completed copies went to nobody,
and the completed copies are yours to hand over. The creator leaving changes nothing.
What your integration should do
- To change anything fixed at send, void the envelope and create a new one.
- If you void through the API, tell the recipients yourself.
- Treat
envelope.voided,envelope.declinedandenvelope.expiredas terminal. - Re-read the envelope when a
recipient.completednames a recipient you do not know, and whenrecipient.delegatedarrives. If it says the delegate is embedded, mint a URL fordelegate_recipient_idwhen you want them in your page. - Expect a recipient’s older signing links to stop working whenever a fresh one is sent, and send support questions about a dead link to the newest email.
- Decide from
GET /api/v1/envelopes/{envelopeId}, not from the body of the last webhook you received: most changes on this page fire none.