> ## Documentation Index
> Fetch the complete documentation index at: https://docs.vumasign.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Changing an envelope after it is sent

> What is fixed at send, what can still change, who can change it, and how you find out.

export const voidNoticeStatuses = "pending, sent, opened, signed or approved";

export const voidNotSentCode = "envelope_not_sent";

export const signingUrlTtl = "10 minutes";

export const routingCc = "cc";

export const recipientRoleDuplicatedCode = "recipient_role_duplicated";

export const recipientGroupResolved = "group_resolved";

export const mintNotSentCode = "envelope_not_sent";

export const liveRecipientStatuses = "pending, sent or opened";

export const invitedRecipientStatuses = "sent or opened";

export const eventRecipientCompleted = "recipient.completed";

export const eventEnvelopeVoided = "envelope.voided";

export const eventEnvelopeExpired = "envelope.expired";

export const eventEnvelopeDeclined = "envelope.declined";

export const envelopeVoided = "voided";

export const envelopeExpired = "expired";

export const envelopeDeclined = "declined";

export const embedDelegated = "delegated";

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

| On the envelope | Field | Fixed from |
| - | - | - |
| The document that is signed | — | Send |
| The template it was made from | `template_id` | Send |
| The brand it was sent under | `brand_id` | Send |
| The signing order: everybody at once, or one after another | — | Send |
| Who sends the completed copy | `completion_delivery` | Send |
| Its roles and their positions: a recipient added later only replaces one | — | Send |
| The documents and their order | — | Send |
| Who the document is about, except whether each of them is present | — | Send |
| Your reference for it | `reference` | Creation |
| Whether it is a sandbox envelope or a live one, decided by the key that created it | — | Creation |

| On each recipient | Field | Fixed from |
| - | - | - |
| Their email address | `email` | Send |
| Their name | `name` | Send |
| The role they fill | `role` | Send |
| Their position in the signing order | — | Send |
| Whether they sign, approve or are copied in | `routing_type` | Send |
| Their job title | `job_title` | Send |
| Their company | `company` | Send |
| Whether they sign in your page or by email | `embedded` | Creation |

**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.** `expires_at` is set when the envelope is created, on
  [`POST /api/v1/envelopes`](/api-reference/create-envelope) and the other create operations, and
  nothing offers a way to move it afterwards. The dashboard shows a deadline; it cannot set or
  change one.
* **The title, and who created it.** `title`, and the person the envelope records as its creator
  (`sender` on
  [`POST /api/v1/envelopes/one-off`](/api-reference/create-one-off-envelope), 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 an email names: see [Who the emails name](#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.

| Change | Who makes it | Through the API | The old link | Webhook |
| - | - | - | - | - |
| Withdraw the envelope | The sender, or your integration | [`POST /api/v1/envelopes/{envelopeId}/void`](/api-reference/void-envelope) | Every link stops working | <code>{eventEnvelopeVoided}</code> |
| Correct a recipient’s name or address | The sender | No: dashboard only | The recipient is retired, and a link they held stops working. A <code>{routingCc}</code> recipient, or one whose turn has not come, was never sent one | None |
| Hand the document to somebody else | The recipient | No: signer only | The recipient is retired and their link stops working | None |
| Send a recipient a fresh link | The sender | No: dashboard only | Their previous link stops working | None |
| Ask for a fresh link when an emailed one has expired | The recipient | No: signer only | The expired link is replaced by one sent to the invited address | None |
| Remind recipients who have not acted | Automatic, when your organisation has turned reminders on | No: dashboard only, as an organisation setting | Their previous link stops working | None |
| Mint a fresh embedded signing URL | Your integration | [`POST /api/v1/envelopes/{envelopeId}/recipients/{recipientId}/signing-url`](/api-reference/create-signing-url) | Nothing, until the new URL is opened: that ends a session an earlier URL began. An earlier URL not yet opened still works | None |
| Decline | The recipient | No: signer only | Nobody can sign any more, except in [a signing group](#signing-groups) | <code>{eventEnvelopeDeclined}</code> |
| Let the deadline pass | Nobody | Set at creation only | Every link stops working | <code>{eventEnvelopeExpired}</code> |
| Change the document, the fields or who was asked, in place | Nobody | No | | |

When a replacement recipient, or anybody else, later signs or approves, <code>{eventRecipientCompleted}</code>
fires as usual.

## Voiding

[`POST /api/v1/envelopes/{envelopeId}/void`](/api-reference/void-envelope) 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 <code>{envelopeVoided}</code>,
and <code>{eventEnvelopeVoided}</code> 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
<code>{voidNotSentCode}</code>.

⚠️ **A void through the API emails nobody.** A void from the dashboard writes to say the document
was withdrawn to every recipient whose status is {voidNoticeStatuses}: everybody still to act and
everybody who had already signed or approved, <code>{routingCc}</code> recipients included. Embedded recipients are
never written to. 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 {liveRecipientStatuses},
while the envelope is still out for signature, from the envelope in the dashboard. A <code>{routingCc}</code> 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 it is their turn, later if the envelope is
signing one after another and somebody ahead of them has not finished. A <code>{routingCc}</code> replacement is not
asked for anything, and an embedded replacement 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.

No webhook fires. If the recipient was signing in your page, the iframe posts <code>{embedDelegated}</code> (see
[Embedded signing](/guides/embedded-signing)): take the iframe down, re-read the envelope, and mint
a URL for the new recipient when you want them to sign. An embedded replacement is embedded too, so
nobody emails them, and they will never sign unless you mint them a URL.

## Finding the replacement

After a correction or a delegation,
[`GET /api/v1/envelopes/{envelopeId}`](/api-reference/get-envelope) still lists the original
recipient, with one of these statuses:

| `status` | What happened | Replaced? |
| - | - | - |
| `superseded` | The sender corrected this recipient’s name or address in the dashboard. | Yes: a new recipient, with a new `id`, in the same role and position. |
| `delegated` | The recipient handed the document to somebody else from the signing page. | Yes: a new recipient, with a new `id`, in the same role and position. |
| `group_resolved` | Another member of the same signing group signed or approved first. | No. The role is filled by the member who acted. |

The response carries **no link** from a retired recipient to the one who replaced them. Outside a
<code>{routingCc}</code> role or a [signing group](#signing-groups), 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 <code>{routingCc}</code> 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.

⚠️ Because neither change fires a webhook, the first you may hear of a replacement is a
<code>{eventRecipientCompleted}</code> 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.

* **Resending.** The sender can send a fresh invitation to an emailed recipient who signs or
  approves and whose status is {invitedRecipientStatuses}, while the envelope is still out for
  signature, from the dashboard. A <code>{routingCc}</code> 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.** Off unless your organisation sets a cadence 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 <code>{routingCc}</code> 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`](/api-reference/create-signing-url).
  Minting does not cancel an earlier URL: each one stays usable until it is opened, the
  envelope's deadline passes or its {signingUrlTtl} 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 <code>{envelopeDeclined}</code>, nobody else can sign,
and <code>{eventEnvelopeDeclined}</code> fires. Nobody is emailed about it, so the webhook is how you find out. It
is terminal, and the only way forward is a new envelope.

The one exception is a member of a [signing group](#signing-groups) whose other members can still
act: their decline is recorded, the envelope stays open, and no webhook fires. Nothing creates such
a group today.

A <code>{routingCc}</code> 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 <code>{recipientGroupResolved}</code>
with their links revoked. <code>{eventRecipientCompleted}</code> 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 <code>{recipientRoleDuplicatedCode}</code>, and the dashboard refuses the same roster at send. You will not
see <code>{recipientGroupResolved}</code> on an envelope you created; it is described here because the reference names
it.

## Expiry

When an envelope’s `expires_at` passes before everybody has acted, a scheduled sweep marks it
<code>{envelopeExpired}</code>, revokes every outstanding link, and <code>{eventEnvelopeExpired}</code> fires. Nobody acted to produce
it and nobody is emailed about it, so the webhook is how you find 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 <code>{mintNotSentCode}</code>.

## Who the emails name

Each email names a member of your organisation as the person asking. Which member depends on the
email, not on a setting, and it is not always the envelope's creator:

| Email | Names |
| - | - |
| The invitations that go out at send, from the dashboard: to everybody, or to the first in order when signing is one after another | Whoever sends it, who may not be the member who created the draft |
| The invitations that go out at send, through the API | Whoever created the API key; a one-off sent as it is created names its `sender` |
| An invitation that waits for a signer's turn, sent when the one before finishes: every later invitation when signing is one after another | The creator |
| A reminder | The creator |
| A resend from the dashboard | Whoever resends it |
| The invitation to a corrected recipient whose turn has come, sent at once | Whoever made the correction |
| The invitation to a corrected recipient whose turn has not come, sent when it does | The creator |
| The invitation to somebody a recipient handed the document to, always sent at once, since it was that recipient's turn | The creator |
| A fresh link a recipient asked for | The creator |
| The notice of a void from the dashboard | Whoever voided it |
| The completed copies | The creator |

## 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 <code>{eventEnvelopeVoided}</code>, <code>{eventEnvelopeDeclined}</code> and <code>{eventEnvelopeExpired}</code> as terminal.
* Re-read the envelope when a <code>{eventRecipientCompleted}</code> names a recipient you do not know, and when an
  embedded page posts <code>{embedDelegated}</code>.
* 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}`](/api-reference/get-envelope), not from the
  body of the last webhook you received: most changes on this page fire none.