> You are reading the Docusign Developer Documentation. For clean Markdown of any page, append .md to the page URL. > > Documentation indexes by section: > - APIs and SDKs: https://docusign.docs.buildwithfern.com/docs/llms.txt > - Platform 101: https://docusign.docs.buildwithfern.com/platform/llms.txt > - Extension Apps: https://docusign.docs.buildwithfern.com/extension-apps/llms.txt > - Docusign CLI: https://docusign.docs.buildwithfern.com/docusign-cli/llms.txt > > Authentication (OAuth, JWT Grant, M2M): https://docusign.docs.buildwithfern.com/platform/auth > Webhooks and Connect: https://docusign.docs.buildwithfern.com/platform/webhooks > > OpenAPI specifications: https://docusign.docs.buildwithfern.com/openapi.json > MCP server: https://docusign.docs.buildwithfern.com/_mcp/server # Add or replace document in envelope PUT https://demo.docusign.net/restapi/v2.1/accounts/{accountId}/envelopes/{envelopeId}/documents/{documentId} Content-Type: application/pdf Adds or replaces a document in an existing draft or in-process envelope. An in-process envelope is one that has been sent but not yet completed or voided. **Note:** When adding or modifying documents for an in-process envelope, Docusign recommends [locking the envelope](/docs/esign-rest-api/reference/envelopes/envelopelocks/create/) prior to making any changes. To add a new document, set the `documentId` path parameter to a new document ID. To replace a document, set the `documentId` path parameter to the document ID of the existing document. The tabs of the original document will be applied to the new document. For example, a request in cURL looks like this: ```bash $ curl --location --request PUT 'https://demo.docusign.net/restapi/v2.1/accounts/0cdb3ff3-xxxx-xxxx-xxxx-e43af011006d/envelopes/ea4cc25b-xxxx-xxxx-xxxx-a67a0a2a4f6c/documents/1' \ --header 'Authorization: Bearer eyJ...bqg' \ --header 'Content-Disposition: filename="newDocument"' \ --header 'Content-Type: application/pdf' \ --data-binary '@/location/of/document.pdf' ``` If HTML document files contain `` elements with the `src` attribute set to a path or URL, those images will not be displayed. Images in HTML files must be encoded in Base64 format, like this: `Base64 encoded image` ### Related topics * [eSignature API rules and resource limits](/docs/esign-rest-api/esign101/rules-and-limits/) * [How-to guides for working with envelopes](/docs/esign-rest-api/how-to/#working-with-documents) Reference: https://developers.docusign.com/docs/esign-rest-api/reference/envelopes/envelopedocuments/update ## Authentication - `Authorization` header (required) (prefixed with ` Bearer `) — OAuth 2.0 access token (JWT or auth-code grant). Sent as `Authorization: Bearer ` on every request except `GET /v2.1` and `GET /service_information`, which are public discovery endpoints. ## Servers - `https://demo.docusign.net/restapi` (Demo, default) - `https://www.docusign.net/restapi` (Production) ## Request ### Path parameters - `accountId` (string, required) — The external account number (int) or account ID Guid. - `documentId` (string, required) — The unique ID of the document within the envelope. Unlike other IDs in the eSignature API, you specify the `documentId` yourself. Typically the first document has the ID `1`, the second document `2`, and so on, but you can use any numbering scheme that fits within a 32-bit signed integer (1 through 2147483647). Tab objects have a `documentId` property that specifies the document on which to place the tab. - `envelopeId` (string, required) — The envelope's GUID. Example: `93be49ab-xxxx-xxxx-xxxx-f752070d71ec` ### Body (application/pdf) This endpoint expects binary data of type application/pdf. - Binary request body. ## Response ### 200 Successful response. - `addedRecipientIds` (list of string, optional) — If recipients were added by converting form fields into tabs, their IDs appear here. This property is read-only. - `agreementType` (string, optional) - `agreementTypeSource` (string, optional) - `attachmentTabId` (string, optional) — If this document is an attachment to another document in the envelope, this is the ID of the attachment tab it is associated with on the other document. - `authoritativeCopy` (string, optional) — When **true,** marks all of the documents in the envelope as authoritative copies. **Note:** You can override this value for a specific document. For example, you can set the `authoritativeCopy` property to **true** at the envelope level, but turn it off for a single document by setting the `authoritativeCopy` property for the document to **false.** - `authoritativeCopyMetadata` (propertyMetadata, optional) — Metadata about a property. - `availableDocumentTypes` (list of signatureType, optional) - `containsPdfFormFields` (string, optional) — When **true,** the document has editable form fields that are made available through a PDF format. - `display` (string, optional) — This string sets the display and behavior properties of the document during signing. Valid values: - `modal` The document is shown as a supplement action strip and can be viewed, downloaded, or printed in a modal window. This is the recommended value for supplemental documents. - `inline` The document is shown in the normal signing window. This value is not used with supplemental documents, but is the default value for all other documents. - `displayMetadata` (propertyMetadata, optional) — Metadata about a property. - `docGenDocumentStatus` (string, optional) - `docGenErrors` (list of docGenSyntaxError, optional) - `docGenFormFields` (list of docGenFormField, optional) - `documentBase64` (string, optional) — The document's bytes. This field can be used to include a base64 version of the document bytes within an envelope definition instead of sending the document using a multi-part HTTP request. The maximum document size is smaller if this field is used due to the overhead of the base64 encoding. - `documentFields` (list of nameValue, optional) — An object containing information about the custom fields on the document. - `documentId` (string, optional) — The ID of the document that the tab is placed on. This value must refer to the ID of an existing document. - `documentIdGuid` (string, optional) — The GUID of the document. - `documentTemplateId` (string, optional) - `errorDetails` (errorDetails, optional) — This object describes errors that occur. It is only valid for responses, and ignored in requests. - `hasDigitalSignature` (string, optional) - `includeInDownload` (string, optional) — When **true,** the document is included in the combined document download (`documentsCombinedUri`). This is only applied to [supplemental documents](/docs/esign-rest-api/esign101/concepts/documents/supplemental/). The default value is **true.** - `includeInDownloadMetadata` (propertyMetadata, optional) — Metadata about a property. - `isAceGenDocument` (string, optional) - `isDocGenDocument` (string, optional) - `isEdited` (string, optional) - `isExternallyAvailable` (string, optional) - `isFlattened` (string, optional) - `name` (string, optional) — The document's file name. Example: `Q1-Report.docx` - `nameMetadata` (propertyMetadata, optional) — Metadata about a property. - `order` (string, optional) — The order in which to sort the results. Valid values are: - `asc`: Ascending order. - `desc`: Descending order. - `pages` (list of page, optional) — An array of page objects that contain information about the pages in the document. - `signerMustAcknowledge` (string, optional) — Sets how the signer interacts with the supplemental document. Valid values: - `no_interaction` No recipient action is required. - `view` The recipient is required to view the document. - `accept` The recipient is required to accept the document by selecting accept during signing, but is not required to view the document. - `view_accept` The recipient is required to view and accept the document. - `signerMustAcknowledgeMetadata` (propertyMetadata, optional) — Metadata about a property. - `sizeBytes` (string, optional) - `templateLocked` (string, optional) — When **true,** the sender cannot change any attributes of the recipient. Used only when working with template recipients. - `templateRequired` (string, optional) — When **true,** the sender may not remove the recipient. Used only when working with template recipients. - `type` (string, optional) — The type of this tab. Values are: - `Approve` - `CheckBox` - `Company` - `Date` - `DateSigned` - `Decline` - `Email` - `EmailAddress` - `EnvelopeId` - `FirstName` - `Formula` - `FullName` - `InitialHere` - `InitialHereOptional` - `LastName` - `List` - `Note` - `Number` - `Radio` - `SignerAttachment` - `SignHere` - `SignHereOptional` - `Ssn` - `Text` - `Title` - `Zip5` - `Zip5Dash4` - `uri` (string, optional) — The URI for retrieving the document. ## Errors ### 400 Bad Request Error Error encountered. - `errorCode` (string, optional) — The code associated with the error condition. - `message` (string, optional) — A brief message describing the error condition. ## Types ### propertyMetadata Metadata about a property. - `options` (list of string, optional) — An array of option strings supported by this setting. - `rights` (string, optional) — Indicates whether the property is editable. Valid values are: - `editable` - `read_only` ### signatureType This object contains information about the type of signature. - `isDefault` (string, optional) — When **true,** the signature type is the default type. - `type` (string, optional) — The type of signature. Valid values are: - `electronic`: Indicates an **electronic** signature that is used by common law countries such as the United States, United Kingdom, and Australia. This is the default signature type that Docusign uses. - `universal`: Indicates a **digital** signature that is accepted by both common law and civil law countries. To use digital signatures, you must use the [Docusign Signature Appliance](/docs/dsa-api/). For more information, see [Standards Based Signatures](/docs/esign-rest-api/esign101/concepts/standards-based-signatures/). ### docGenSyntaxError Describes document generation errors. - `errorCode` (string, optional) — A code associated with the error condition. - `message` (string, optional) — The error message. - `tagIdentifier` (string, optional) — The tag that caused the syntax error. See [Document Generation Syntax](https://support.docusign.com/s/document-item?bundleId=als1679428547895&topicId=ftc1679700030026.html) to learn more about document generation syntax rules. ### docGenFormField The document fields available for document generation. This object is used in reponses (GET) and requests (PUT). When used with [DocumentGeneration: updateEnvelopeDocGenFormFields](/docs/esign-rest-api/reference/envelopes/documentgeneration/updateenvelopedocgenformfields/) (PUT), the `name` and `value` / `rowValues` properties are required and any other values are ignored. - `children` (list of docGenFormField, optional) - `connectedObjectDetails` (connectedObjectDetails, optional) - `defaultValue` (string, optional) - `description` (string, optional) — A description of the field. Displayed with the label. - `filter` (DocGenFormFieldFilter, optional) - `format` (docGenFormat, optional) - `fullyQualifiedPath` (string, optional) — Reserved for Docusign use. This value is returned in the `getEnvelopeDocGenFormFields` response but should not be included in `updateEnvelopeDocGenFormFields` requests. - `hidden` (boolean, optional) - `label` (string, optional) — A label displayed near the field. - `name` (string, optional) — The name of the sender field. Required for PUT requests. - `options` (list of docGenFormFieldOption, optional) — When `type` is `Select`, this array describes the available options. - `order` (string, optional) — Not currently used. - `predefinedValidation` (string, optional) — Reserved for Docusign. - `readOnly` (boolean, optional) - `required` (string, optional) — When **true,** the field is required. - `rowValues` (list of docGenFormFieldRowValue, optional) — For fields of type `TableRow`, this property represents the sender fields in the row. For GET requests, this array contains a single `docGenFormFieldRowValue` object. That object contains a list of sender fields that will appear in each row. For PUT requests, you must supply a `docGenFormFieldRowValue` object for each row in the table. This populates the data in the table. - `type` (string, optional) — The kind of data the sender field holds. Valid values: - `TextBox` - `Date` - `Number` - `Select` - `TableRow` - `validation` (docGenFormFieldValidation, optional) — Describes how values are validated. - `value` (string, optional) — The value of the sender field. For PUT requests, you must supply either this property (for all fields except `TableRow` types) or `rowValues` (for `TableRow` fields). ### nameValue A name-value pair that describes an item and provides a value for the item. - `errorDetails` (errorDetails, optional) — This object describes errors that occur. It is only valid for responses, and ignored in requests. - `name` (string, optional) — The name of the item. - `originalValue` (string, optional) — The initial value of the item. - `value` (string, optional) — The current value of the item. ### errorDetails This object describes errors that occur. It is only valid for responses, and ignored in requests. - `errorCode` (string, optional) — The code associated with the error condition. - `message` (string, optional) — A brief message describing the error condition. ### page Description of a page of a document. - `dpi` (string, optional) — The number of dots per inch used for the page image. - `errorDetails` (errorDetails, optional) — This object describes errors that occur. It is only valid for responses, and ignored in requests. - `height` (string, optional) — The height of the page in pixels. Must be an integer. - `imageBytes` (string, optional) — The number of image bytes. - `mimeType` (string, optional) — The MIME type. - `pageId` (string, optional) — The ID of the page. - `sequence` (string, optional) — The sequence of the page in the document, or page number. - `width` (string, optional) — The width of the page in pixels. Must be an integer. ### connectedObjectDetails - `recordId` (string, optional) ### DocGenFormFieldFilter ### docGenFormat - `expression` (string, optional) - `locale` (string, optional) ### docGenFormFieldOption Specifies an individual option setting when type is `Select`. - `description` (string, optional) — Description of the selectable option. - `label` (string, optional) — The label for the selectable option. - `selected` (string, optional) — When **true,** the option is selected. - `value` (string, optional) — Specifies the value of the option. This is the value of the form field when this option is selected. ### docGenFormFieldRowValue An object representing a row of a dynamic table. - `docGenFormFieldList` (list of docGenFormField, optional) — The sender fields in each row of the table. For GET requests, the `label`, `type`, `required`, and `name` properties will be returned. For POST requests, supply the `name` and `value` for each child object. These correspond to the values in each column. ### docGenFormFieldValidation Describes how values are validated. - `errorMessage` (string, optional) — The error message when validation fails. - `expression` (string, optional) — The expression used to validate values. ## Examples **Response** ```json { "addedRecipientIds": [ "string" ], "agreementType": "string", "agreementTypeSource": "string", "attachmentTabId": "string", "authoritativeCopy": "string", "authoritativeCopyMetadata": { "options": [ "string" ], "rights": "string" }, "availableDocumentTypes": [ { "isDefault": "string", "type": "string" } ], "containsPdfFormFields": "string", "display": "string", "displayMetadata": { "options": [ "string" ], "rights": "string" }, "docGenDocumentStatus": "string", "docGenErrors": [ { "errorCode": "string", "message": "string", "tagIdentifier": "string" } ], "docGenFormFields": [ { "children": [ null ], "connectedObjectDetails": { "recordId": "string" }, "defaultValue": "string", "description": "string", "filter": {}, "format": { "expression": "string", "locale": "string" }, "fullyQualifiedPath": "string", "hidden": true, "label": "string", "name": "string", "options": [ { "description": "string", "label": "string", "selected": "string", "value": "string" } ], "order": "string", "predefinedValidation": "string", "readOnly": true, "required": "string", "rowValues": [ { "docGenFormFieldList": [ null ] } ], "type": "string", "validation": { "errorMessage": "string", "expression": "string" }, "value": "string" } ], "documentBase64": "string", "documentFields": [ { "errorDetails": { "errorCode": "string", "message": "string" }, "name": "string", "originalValue": "string", "value": "string" } ], "documentId": "string", "documentIdGuid": "string", "documentTemplateId": "string", "errorDetails": { "errorCode": "string", "message": "string" }, "hasDigitalSignature": "string", "includeInDownload": "string", "includeInDownloadMetadata": { "options": [ "string" ], "rights": "string" }, "isAceGenDocument": "string", "isDocGenDocument": "string", "isEdited": "string", "isExternallyAvailable": "string", "isFlattened": "string", "name": "string", "nameMetadata": { "options": [ "string" ], "rights": "string" }, "order": "string", "pages": [ { "dpi": "string", "errorDetails": { "errorCode": "string", "message": "string" }, "height": "string", "imageBytes": "string", "mimeType": "string", "pageId": "string", "sequence": "string", "width": "string" } ], "signerMustAcknowledge": "string", "signerMustAcknowledgeMetadata": { "options": [ "string" ], "rights": "string" }, "sizeBytes": "string", "templateLocked": "string", "templateRequired": "string", "type": "string", "uri": "string" } ```