Cancel an eSign Session

This guide walks you through the process of canceling an entire eSign session (signature order) using the Stewart Sign API. When canceled, participants are prevented from signing and notification emails are sent to affected signers.

When to Use

Canceling an eSign session is equivalent to DocuSign's "Decline to Sign" — it voids the entire transaction for everyone involved. Common scenarios include:

• A signer declines to electronically sign
• The sender needs to void the request and resubmit
• Documents need to be corrected before signing

Requirements

1. You need to have Node.js installed on your system.
2. You'll also need the axios library. You can install it using the following command:

npm install axios

3. A valid Bearer token (JWT) for authentication.
4. The eSign session ID or transaction ID of the eSign session you want to cancel. Both ID types are accepted — the API will resolve the eSign session from either. These IDs are returned in the response body when creating a transaction.

Request Body

The request body is optional. All fields are optional.

Field	Type	Required	Description
cancellationRequestor	string (UUID)	No	The Participant ID of the signer who initiated the cancellation. The participant's full name is resolved server-side and included in the cancellation notification email sent to all notified participants.

Note: The following fields are automatically injected by the server from the authenticated token and do not need to be supplied by the caller: canceledBy (the authenticated user's ID), organizationId, and source (always set to "api").

Code Snippet

Use the following code snippet to cancel an eSign session. Replace <transactionId> with the actual transaction ID, and <accessToken> with your API access token.

const axios = require("axios");

const config = {
  method: "post",
  url: `https://public-api.sign.stewart.com/esign/<transactionId>/cancel`,
  headers: {
    Authorization: "Bearer <accessToken>",
    "Content-Type": "application/json",
  },
  data: {
    // Optional: Participant ID of the signer who initiated the cancellation.
    // The participant's full name will be resolved server-side and included
    // in the cancellation notification email.
    cancellationRequestor: "<participantId>",
  },
};

axios(config)
  .then(function (response) {
    console.log("eSign session canceled successfully", response.data);
  })
  .catch(function (error) {
    console.log(error.response?.data || error.message);
  });

Successful Response

On success, the API returns the eSign and transaction IDs:

{
  "id": "ab16ae12-cb29-4693-8958-c4905e4ff978",
  "transactionId": "5c19c06b-99f8-4260-8e5a-261ca8922e43"
}

What Happens After Cancellation

1. Order status transitions to Canceled
2. Notification emails are sent with:
   • The date and time of the cancellation
   • The name of the requestor who initiated the cancellation (if cancellationRequestor was provided in the request body)
3. Who receives the notification depends on the session's signing order configuration:
   • Signing order disabled: all participants receive the cancellation email
   • Signing order enabled: only participants who have already completed signing and the current active signer are notified; participants queued for future signing steps are not emailed
4. CC recipients: if the eSign session has an assigned group, the group's configured CC email addresses are also included in the cancellation notification
5. Signing links become invalid — any signer attempting to access them will see an error
6. No further signing actions are permitted on the order
7. An audit trail entry is recorded with the cancellation details

Error Responses

Status	Reason
400 Bad Request	transaction_id is not a valid UUID, or the session is in draft status and cannot be canceled
404 Not Found	No eSign session was found with the provided transaction ID
409 Conflict	The session is already completed or canceled
500 Internal Server Error	An unexpected server-side error occurred
503 Service Unavailable	The Transaction service is unreachable (connection refused or timed out)

Steps to Execute the Code Snippet

1. Create a new file named cancel_esign.js.
2. Copy and paste the code snippet provided above into the new file.
3. Replace <transactionId> and <accessToken> with the appropriate values.
4. Save the file and open a terminal or command prompt.
5. Navigate to the folder where you saved the cancel_esign.js file.
6. Run the following command to execute the script:

node cancel_esign.js

If the request is successful, you'll see a message indicating that the eSign session was canceled successfully. In case of an error, the error details will be displayed instead.

Additional Resources

For more information about the eSign API, visit the API reference.

If you need further assistance or have questions, feel free to reach out to our support team.