Skip to content

Cookbook

Replace a recipient who left the company

Swap the person who should sign an in-progress envelope, then create a ceremony for the replacement so the new recipient receives the signing request.

A signer changed jobs, or the wrong person was assigned. Replace them without cancelling the envelope: the replacement takes over the same key, position and places, and everyone else’s progress is kept.

There are two calls. Replacing creates the new recipient, and creating a ceremony for it sends the request.

Node.js
const API = "https://api.signatureapi.com/v1";
const headers = { "X-API-Key": process.env.SIGNATUREAPI_KEY, "Content-Type": "application/json" };

async function replaceRecipient(envelopeId, recipientKey, name, email) {
  // Find the current recipient by its key.
  const envelope = await (await fetch(`${API}/envelopes/${envelopeId}`, { headers })).json();
  const current = envelope.recipients.find((r) => r.key === recipientKey);

  // 1. Replace. The new recipient has a new id.
  const replaced = await fetch(`${API}/recipients/${current.id}/replace`, {
    method: "POST",
    headers,
    body: JSON.stringify({ name, email }),
  });
  if (!replaced.ok) throw new Error(`replace failed: ${replaced.status}`);
  const next = await replaced.json();

  // 2. Create a ceremony. With email_link, SignatureAPI emails the signing link.
  const ceremony = await fetch(`${API}/recipients/${next.id}/ceremonies`, {
    method: "POST",
    headers,
    body: JSON.stringify({ authentication: [{ type: "email_link" }] }),
  });
  if (!ceremony.ok) throw new Error(`ceremony failed: ${ceremony.status}`);

  return next.id; // store this in place of the old id
}
Python
import os

import requests

API = "https://api.signatureapi.com/v1"
HEADERS = {"X-API-Key": os.environ["SIGNATUREAPI_KEY"]}


def replace_recipient(envelope_id, recipient_key, name, email):
    # Find the current recipient by its key.
    envelope = requests.get(f"{API}/envelopes/{envelope_id}", headers=HEADERS).json()
    current = next(r for r in envelope["recipients"] if r["key"] == recipient_key)

    # 1. Replace. The new recipient has a new id.
    replaced = requests.post(f"{API}/recipients/{current['id']}/replace", headers=HEADERS, json={"name": name, "email": email})
    replaced.raise_for_status()
    new = replaced.json()

    # 2. Create a ceremony. With email_link, SignatureAPI emails the signing link.
    ceremony = requests.post(f"{API}/recipients/{new['id']}/ceremonies", headers=HEADERS, json={"authentication": [{"type": "email_link"}]})
    ceremony.raise_for_status()

    return new["id"]  # store this in place of the old id
  • Store the new id. Later events such as recipient.sent and recipient.completed carry the new recipient’s id. A recipient.replaced event is emitted for the old one.
  • Without a ceremony nothing is sent. In a sequential envelope the recipients after it keep waiting until the replacement has a ceremony.
  • What can be replaced. A recipient who hasn’t completed, in an envelope that is processing or in_progress. Completed and already replaced recipients and automatic signers return 409 cannot-replace. A recipient who bounced or declined can be replaced.
  • Same ceremony settings? The replacement starts without a ceremony, so pass the authentication, redirect or embedding settings you want in the ceremony request.