Update a Transaction

This guide walks you through updating an existing eSignature transaction using the Stewart Sign API. The PUT endpoint replaces the transaction's data with the provided payload.

When to Use

Updating a transaction is useful when you need to:

• Modify participant details before signing begins
• Change the transaction status (e.g., from draft to esign_pending)
• Update document metadata or tags
• Add or change a personalized message
• Enable or disable signing order

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 transaction ID of the eSignature transaction you want to update.

Endpoint

PUT /transactions/{id}

Parameter	Type	Required	Description
id	string (UUID)	Yes	The unique identifier of the eSignature transaction to update.

Request Body

The request body accepts the same fields as the create transaction endpoint. All fields are optional — only include the fields you want to update.

Field	Type	Required	Description
brandId	string (UUID)	No	The ID of the brand to apply to this transaction. The brand must belong to your organization. See Brands for details on retrieving available brands.
documents	array	No	Updated list of documents with tags
participants	array	No	Updated list of participants. Set viewOnly: true on a participant to make it a view-only recipient.
status	string	No	Transaction status: draft, esign_pending, tagging_in_progress
notifyParticipants	object	No	Notification preferences (e.g., { "email": true })
signingOrder	boolean	No	Enable or disable signing order
personalizedMessage	string	No	Custom email message body included in the signing email
emailSubject	string	No	Custom email subject line for signer notification emails (max 255 chars). If omitted, the system default subject is used.
referenceId	string	No	Your organization's unique reference ID
taggingOrganizationId	string	No	Organization ID assigned to tag the document
taggingUserId	string	No	User ID assigned to tag the document

Code Snippet

Use the following code snippet to update a transaction. Replace <transactionId> with the actual transaction ID, and <accessToken> with your API access token.

const axios = require("axios");

const transactionId = "<transactionId>";

const config = {
  method: "put",
  url: `https://public-api.sign.stewart.com/transactions/${transactionId}`,
  headers: {
    Authorization: "Bearer <accessToken>",
    "Content-Type": "application/json",
  },
  data: {
    status: "esign_pending",
    personalizedMessage: "Please review and sign the updated documents.",
    signingOrder: true,
    notifyParticipants: {
      email: true,
    },
  },
};

axios(config)
  .then(function (response) {
    console.log("Transaction updated successfully:", response.data);
  })
  .catch(function (error) {
    console.log(error.response?.data || error.message);
  });

Successful Response

On success, the API returns the updated transaction object:

{
  "id": "391866a6-8ebb-4533-b6ab-c7bb4d6fbd38",
  "status": "esign_pending",
  "documents": [...],
  "participants": [...]
}

Error Responses

Status	Reason
400 Bad Request	Invalid request payload, or invalid brandId (not found or doesn't belong to your organization)
401 Unauthorized	Invalid or expired Bearer token
409 Conflict	Cannot update a canceled eSign transaction

Steps to Execute the Code Snippet

1. Create a new file named update_transaction.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 update_transaction.js file.
6. Run the following command to execute the script:

node update_transaction.js

If the request is successful, you'll see the updated transaction details displayed in the console. In case of an error, the error details will be displayed instead.

V2-12387 — New request fields

The following optional fields are now accepted on PUT /transactions/:id (and on POST /transactions, with the exception that emailSubject was already supported on create):

Field	Type	Feature flag	Notes
showConfetti	boolean	—	Whether a confetti animation plays after signing completes.
useReplyTo	boolean	enableReplyTo	Whether outgoing eSign emails include a Reply-To header. May be overridden by brand — see GET transaction by ID.
replyToEmail	string	enableReplyTo	Order-level Reply-To address. Validated as a well-formed email when not null.
assignedGroupId	UUID	teamAssignment	Team/group to assign this transaction to. Discover IDs via GET /teams.
allowSignerNameEdit	boolean	signersNameEdit	Whether signers may edit their own name during signing.
emailSubject	string	—	New on PUT. Custom email subject line. Maximum 255 characters. Previously create-only.
fileReference	string	—	Initiator-supplied tracking identifier stored on the Transaction record. Distinct from referenceId.

PUT clear semantics

PUT /transactions/:id honors the following convention for nullable fields:

• Omit the field → leave the current value unchanged.
• Send null → clear / reset the field (where the field is nullable). Applies to replyToEmail, assignedGroupId, emailSubject, and fileReference.
• Send a value → replace.

When a gated field is present in the payload (including null), the request is rejected with 403 enl-api-403 if the corresponding feature flag is not enabled for your organization — even when you are only attempting to clear the field. Contact your account manager to enable the flag, or remove the field from the request.

Feature-flag error response

{
  "error": "enl-api-403",
  "message": "Forbidden. Feature not available.",
  "detail": "'assignedGroupId' requires the 'teamAssignment' feature, which is not enabled for your organization."
}

Additional Resources

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

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