Skip to content
  1. Blog
  2. API

How to Change the Recipient of an eSignature Document via API

TL;DR: Send a PATCH request to /v1/document/changeRecipient with the document ID, the old signer’s email, the new signer’s name and email, and a reason. We swap the signer on the same document and email the new person a signing link. Our eSignature API page shows what else the API can do.

You sent a contract to a client’s old work address. Or the person who should sign is on leave, and a colleague will sign instead. The document is out, and the wrong person has the link.

You do not need to cancel the request and start again. You can change the recipient of a document that is still waiting for that signer, and keep everything else as it was.

What does changing the recipient of a document mean?

Changing the recipient means you replace one signer on a sent document with another person. The document, its fields and any signatures already on it stay the same.

Think of a parcel with the wrong name on the label. You fix the label and send it on, instead of packing a new box.

When can you change the recipient of an eSignature document?

You can change a recipient while that person has not signed and the document is still open. You cannot edit a document that is completed, declined, revoked or expired.

A document with two or more recipients works signer by signer. Even after one person signs, you can still change anyone who has not signed yet.

Our help article on how to change the recipient of a document shows the same task in the web app.

What do you need before you call the API?

Have these details ready before you write the request:

  • The document ID, which you got back when you sent the document.
  • The email address of the signer you want to replace.
  • The new signer’s name and email address.
  • A short reason for the change, such as “Wrong email address”.

You also need an API key from your BoldSign account. The request body must hold the new signer’s name and a reason.

How do you change the recipient of an eSignature document via API?

Send a PATCH request to https://api.boldsign.com/v1/document/changeRecipient with the document ID in the query string. Put the new and old signer details and your reason in the JavaScript Object Notation (JSON) body.

  1. Copy the document ID and add it as documentId in the request address.
  2. Set oldSignerEmail to the address of the signer you want to replace.
  3. Set newSignerName and newSignerEmail for the person who will sign.
  4. Add a reason and send the request with your API key in the X-API-KEY header.

Our developer guide on how to change the recipient holds the same request with more notes.

What does the code look like in each language?

Each sample below replaces Alex (alex@example.com) with Sam (sam@example.com) on one document. Swap in your own API key, document ID and addresses.

curl -X 'PATCH' \
  'https://api.boldsign.com/v1/document/changeRecipient?documentId={Your document Id}' \
  -H 'X-API-KEY: {your API key}' \
  -H 'Content-Type: application/json' \
  -d '{
  "newSignerName": "{New signer name}",
  "reason": "{Reason to change signer}",
  "newSignerEmail": "{New signer email}",
  "oldSignerEmail": "{Old signer email}"
}'
var apiClient = new ApiClient("https://api.boldsign.com", "{your API key}");
var documentClient = new DocumentClient(apiClient);

documentClient.ChangeRecipient(
    "{Your document Id}",
    "{Old signer email}",
    "{Reason to change signer}",
    "{New signer name}",
    "{New signer email}"
);
import boldsign

configuration = boldsign.Configuration(host="https://api.boldsign.com", api_key="YOUR_API_KEY")

with boldsign.ApiClient(configuration) as api_client:

    document_api = boldsign.DocumentApi(api_client)

    change_recipient_request = boldsign.ChangeRecipient(
        old_signer_email="alex@example.com",
        new_signer_name="Sam",
        new_signer_email="sam@example.com",
        reason="Reason to change signer",
    )

    response = document_api.change_recipient(
        document_id="Your_document_Id", change_recipient=change_recipient_request
    )
<?php
require_once "vendor/autoload.php";

use BoldSign\Configuration;
use BoldSign\Api\DocumentApi;
use BoldSign\Model\ChangeRecipient;

$config = new Configuration();
$config->setHost('https://api.boldsign.com');
$config->setApiKey('YOUR_API_KEY');

$documentApi = new DocumentApi($config);

$documentId = 'YOUR_DOCUMENT_ID';
$oldSignerEmail = 'alex@example.com';
$newSignerEmail = 'sam@example.com';
$newSignerName = 'Sam';
$reason = 'Signer replacement requested';

$changeRecipient = new ChangeRecipient();

$changeRecipient->setOldSignerEmail($oldSignerEmail);
$changeRecipient->setNewSignerEmail($newSignerEmail);
$changeRecipient->setNewSignerName($newSignerName);
$changeRecipient->setReason($reason);

$documentApi->changeRecipient($documentId, $changeRecipient);
try {
ApiClient apiClient = Configuration.getDefaultApiClient();
apiClient.setApiKey("YOUR_API_KEY");
DocumentApi documentApi = new DocumentApi(apiClient);
String documentId = "DOCUMENT_ID";
String oldSignerEmail = "alex@example.com";
String reason = "Wrongly sent";
String newSignerName = "Sam";
String newSignerEmail = "sam@example.com";
ChangeRecipient changeRecipient = new ChangeRecipient();
changeRecipient.setOldSignerEmail(oldSignerEmail);
changeRecipient.setReason(reason);
changeRecipient.setNewSignerName(newSignerName);
changeRecipient.setNewSignerEmail(newSignerEmail);
documentApi.changeRecipient(documentId, changeRecipient);
System.out.println("Recipient changed successfully for document ID: " + documentId);
}
catch (ApiException e) {
    System.err.println("API call failed: " + e.getMessage());
}
catch (Exception e) {
    System.err.println("An unexpected error occurred: " + e.getMessage());
}
import { DocumentApi, ChangeRecipient } from "boldsign";

const documentApi = new DocumentApi("https://api.boldsign.com");
documentApi.setApiKey("YOUR_API_KEY");

// Create request object
const changeRecipient = new ChangeRecipient();
changeRecipient.newSignerName = "Sam";
changeRecipient.newSignerEmail = "sam@example.com";
changeRecipient.oldSignerEmail = "alex@example.com";
changeRecipient.reason = "Wrongly sent";

const documentId = "YOUR_DOCUMENT_ID";

async function changeDocumentRecipient() {
  try {
    await documentApi.changeRecipient(documentId, changeRecipient);
    console.log("Recipient changed successfully!");
  } catch (error: any) {
    console.error("Error occurred while calling the API:", error.message);
  }
}

changeDocumentRecipient();

What happens after the recipient changes?

The new signer gets an email with a link to sign the document. We also tell the old recipient about the change.

The document keeps its ID, so your app can go on tracking it as before. To control which emails go out, see our guide on how to control recipient notifications via the BoldSign API.

What should you watch out for?

A few details save you a failed call or a confused signer:

  • Check the document status first, since a completed or expired document cannot change.
  • Use the exact email of the signer you are replacing.
  • Write a reason the next reader will understand, such as “Signer left the company”.
  • Use the edit document endpoint to change fields or files as well.

Our guide to the BoldSign edit document API covers that wider edit.

Which plan do you need for the API, and what does it cost?

Live API access comes with the Enterprise API plan, which starts at $30 a month with 40 envelopes. Extra envelopes cost $0.75 each.

You can build and test first in our free API sandbox, with no credit card. Sandbox documents carry a test watermark and are deleted after 14 days. Prices are in USD, as listed on the BoldSign pricing page in November 2026.

Where do you go next with signer changes via API?

Try the request on a test document in the sandbox first. Then add it to the part of your app where users fix mistakes.

Frequently asked questions

Can I change a signer after I send a document for signature?

Yes, as long as that signer has not signed yet. You give the document ID, the new name and email, and a reason, and we send the signing link to the new person.

What happens to the old recipient's signing link?

We tell the old recipient about the change. The new recipient gets an email with a fresh signing link to the document.

Which fields does the change recipient request need?

The request body needs the new signer's name and a reason. You also pass the document ID in the address, plus the old and new email addresses to show which signer to replace.

Can I change a recipient on a completed document?

No. A completed, declined, revoked or expired document is locked, so its recipients stay as they are.

Can I replace one signer after another signer has signed?

Yes. On a document with two or more recipients, you can still change anyone who has not signed. Signatures already on the document stay in place.

Does changing the recipient restart the whole document?

No. You keep the same document ID, and only the signer you name is swapped. You do not need to revoke the request and send it again.

Is a document still legally valid after I change the signer?

Yes, when the new signer agrees to sign electronically and the signed record is kept. Each change also carries the reason you gave for it.

Can I test the change recipient endpoint for free?

Yes. Our free API sandbox needs no credit card. Sandbox documents carry a test watermark and are deleted after 14 days.

Starvritsa Buhungi

Starvritsa is a Technical Assistant at BoldSign, channelling her passion into crafting top-tier content for users through meticulous documentation. She creates content across various formats, including API tutorials, help articles, and comprehensive guides.

More posts by Starvritsa Buhungi
Get started

Sign up for your free trial today!

Start free trial
  • 30-day free trial
  • No credit card required