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.sentandrecipient.completedcarry the new recipient’s id. Arecipient.replacedevent 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
processingorin_progress. Completed and already replaced recipients and automatic signers return409cannot-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.