Envelope Update

Replaces the contents of an envelope that has been created but not yet sent. The envelope must be in Draft status.

The same Storage prerequisite applies as on signatures-envelope-create: every document named in the request must already have been uploaded through signatures-document-upload and be referenced by its storage id, within the 24-hour window. Replacing the document list means re-supplying those ids, not just the ones that changed.

The request body is the same shape as signatures-envelope-create, and it replaces the draft entirely: documents, recipients, sign groups and fields are all overwritten by what is sent, not merged into what is already there. Envelope settings and metadata are replaced the same way.

Use this to revise a draft before sending it. Once an envelope has been sent, its documents, recipients and fields are fixed — signatures-envelope-update applies only while the envelope is still in Draft. The expiration settings (expireInDays and alertDaysBeforeExpiry) are the only things that can still be changed, through signatures-envelope-edit.

Authorization

AuthorizationBearer <token>

JWT token to authenticate the request.

In: header

X-Api-Key<token>

API key, sent as a request header.

In: header

Path Parameters

envelopeId*string

GUID of the envelope to update, as returned by signatures-envelope-create in result.data.envelope.id. The envelope must still be in Draft status.

Formatuuid

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

Body for creating or updating a signature envelope. It follows the standard request envelope: an optional externalContext supplied by the caller and echoed back unchanged, alongside the named sections that describe the envelope — documents, recipients, fields, signGroups and envelope.

The sections are linked by client-assigned reference ids rather than server ids, because no server ids exist until the envelope is created. Each document, recipient and sign group carries an id you choose, and fields points at those ids. Every reference id must be unique within the request — duplicates are rejected with DUPLICATE_REFERENCE_DOCUMENT_ID, DUPLICATE_REFERENCE_RECIPIENT_ID or DUPLICATE_REFERENCE_SIGNGROUP_ID. The response returns the server-generated id for every object created.

documents*array<>

The documents the envelope is built from. Mandatory, and must contain at least one entry — an absent list is rejected with NO_DOCUMENTS, an empty one with DOCUMENT_LIST_CANNOT_BE_EMPTY.

Items1 <= items

fields?array<>

The fields placed on the documents for recipients to complete or sign. Optional.

recipients*array<>

The people who receive the envelope and what each of them may do with it. Mandatory, and must contain at least one entry — an absent list is rejected with NO_RECIPIENTS, an empty one with RECIPIENT_LIST_CANNOT_BE_EMPTY.

Items1 <= items

signGroups?array<>

Groups of recipients that share a role, a position in the signing order and a set of fields, so a field can be assigned to the group rather than to one named person. Optional.

envelope?

Settings that apply to the envelope as a whole: the notification email, the sender shown to recipients, signing order, expiry, reminders and notifications.

externalContext?unknown

Arbitrary JSON object supplied by the caller and echoed back unchanged in the response envelope, for correlating a request with its response. Its shape is not validated or interpreted.

Response Body

`application/json`

curl -X PUT "https://example.com/signatures/envelope/66e0fdcc-3b59-46e8-aef9-f55cb2cad859/update" \  -H "Content-Type: application/json" \  -d '{    "documents": [      {        "referenceDocumentId": 1,        "name": "Test Document Name",        "loadMethod": "Storage",        "urn": "{{uploadedDocument}}"      }    ],    "recipients": [      {        "referenceSignerId": 1,        "name": "Test Example",        "email": "user@example.com",        "role": "signer",        "mandatory": true      }    ],    "fields": [      {        "type": "signature",        "isRequired": true,        "referenceSignerId": 1,        "referenceDocumentId": 1,        "positionX": 10,        "positionY": 10,        "height": 100,        "width": 100,        "page": 1,        "name": "mds_signature1",        "properties": {          "fontFamily": "Arial",          "fontSize": 13,          "color": "red",          "bold": true,          "italic": true,          "underline": true,          "textAlign": "center"        }      }    ],    "envelope": {      "subject": "Email Subject",      "message": "Email Message",      "senderName": "Sender",      "senderEmail": "sender@example.com",      "isSignOrder": false,      "expireInDays": 5,      "alertDaysBeforeExpiry": 5,      "firstReminderDays": 3,      "repeatingReminderDays": 2,      "notifyWhenOpened": true,      "notifyWhenSigned": true    },    "externalContext": {      "id": "12345"    }  }'

{  "result": {    "statusCode": 200,    "message": "OK",    "data": {      "envelope": {        "id": "86af240d-5b18-407a-a91a-9d56b22e0d64",        "status": "Draft"      },      "documents": [        {          "id": "0ae5ef4d-e165-4ca7-9f17-7747497381e4",          "externalContext": {}        }      ],      "recipients": [        {          "id": "733c28bf-5765-42ba-8f12-f5b8ee6c7b8f",          "externalContext": {}        }      ],      "signGroups": [        {          "id": "449fa746-0ee3-4fc2-bee5-1d63211c3900"        }      ],      "fields": [        {          "id": "bf1da0a5-4546-42ab-b0a1-cbbdec2c356d",          "recipientId": "90118fc2-0ac2-46a5-83f4-175a5f7befa1",          "signGroupId": "6a539983-f5d3-4afe-b31a-ba1874028d00",          "documentId": "523583a7-9fae-450c-b667-5fe9beb1b771"        }      ]    }  },  "origin": "PUT https://api.doctavian.com/v1/signatures/envelope/{envelopeId}/update",  "dateTime": "2026-07-20T12:00:00.000Z",  "userId": "c7dd9746-1319-4d7f-873b-a0ee308e9fc6",  "operationId": "c05e8b1734af4d92ba67e0d3915fc8ae"}

{  "error": {    "message": "Envelope not found.",    "statusCode": 400,    "innerErrors": [      {        "code": "ENVELOPE_ID_INVALID",        "message": "Envelope not found.",        "userMessage": "Envelope not found."      }    ]  },  "origin": "PUT https://api.doctavian.com/v1/signatures/envelope/{envelopeId}/update",  "dateTime": "2026-07-20T12:00:00.000Z",  "userId": "fdca0d75-1921-4740-b242-6ccd781a9f41",  "operationId": "e02e601856daae60d5b2db9c4edb3618"}

{  "error": {    "statusCode": 500,    "message": "An unexpected error occurred while updating the envelope.",    "innerErrors": [      {        "code": "FUNCTION_EXECUTION_ERROR",        "message": "An unexpected error occurred while updating the envelope.",        "userMessage": "Something went wrong. Please try again or contact support."      }    ]  },  "origin": "PUT https://api.doctavian.com/v1/signatures/envelope/{envelopeId}/update",  "dateTime": "2026-07-20T12:00:00.000Z",  "userId": "06479744-1473-4dc3-84b2-60e7010215e3",  "operationId": "4be65ed72ddbf787f0cbd8d587aa34a0"}

Authorization

Path Parameters

Request Body

Response Body

200application/json

400application/json

500application/json

`application/json`

`application/json`

`application/json`