Skip to main content
Sending is the point after which most of an envelope stops being editable. The document, its fields and the people who were asked become part of the record the moment it leaves, and the product refuses to rewrite them. What can still happen is a short list: the envelope can be withdrawn, a recipient can be replaced, a signing link can be reissued, somebody can decline, and the deadline can be extended or can pass. Most of those are not API calls, and most of them fire no webhook. This page says which are which, so you know when to wait for an event, when to call an endpoint and when to re-read the envelope.

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_at is set when the envelope is created, on POST /api/v1/envelopes and 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 (sender on POST /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_ref never changes on that recipient. Anybody who takes their place after send, by a correction or a delegation, is a new recipient with a new id and starts without one. On a draft, saving the recipients in the dashboard keeps each one whose address is unchanged, with its id, 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.
To change any of these, void the envelope and send a new one. Signatures collected on the old envelope stay on the old envelope and do not carry over.

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. A cc 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. 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 cc recipient 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 cc recipients 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.
None of these fires a webhook. The envelope’s history shows each fresh link.

Declines

Declining is signer only. A decline ends the envelope: it becomes declined, 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 as group_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 it expired.

Expiry

When an envelope’s expires_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, so POST /api/v1/envelopes/{envelopeId}/send sends a draft in its creator’s name whichever key calls it, exactly as sending it when it is created would have.
If that member later leaves your organisation, nothing more can be emailed in their name. Sending a draft through the API whose creator has left is refused as 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.declined and envelope.expired as terminal.
  • Re-read the envelope when a recipient.completed names a recipient you do not know, and when recipient.delegated arrives. If it says the delegate is embedded, mint a URL for delegate_recipient_id when 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.