Skip to navigation
Docusign eSignature REST APIEnvelopesEnvelopeDocuments

Add or replace document in envelope

View as Markdown

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 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:

$ 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 <img> 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: <img src="data:image/gif;base64,R0lGODlh...IQAAOw==" alt="Base64 encoded image" width="150" height="150"/>

Authentication

AuthorizationBearer

OAuth 2.0 access token (JWT or auth-code grant). Sent as Authorization: Bearer <token> on every request except GET /v2.1 and GET /service_information, which are public discovery endpoints.

Path parameters

accountIdstringRequired

The external account number (int) or account ID Guid.

documentIdstringRequired

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.

envelopeIdstringRequired

The envelope’s GUID.

Example: 93be49ab-xxxx-xxxx-xxxx-f752070d71ec

Request

Updated document content.

Response

Successful response.
addedRecipientIdslist of stringsOptional

If recipients were added by converting form fields into tabs, their IDs appear here. This property is read-only.

agreementTypestringOptional
agreementTypeSourcestringOptional
attachmentTabIdstringOptional
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.
authoritativeCopystringOptional

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.

authoritativeCopyMetadataobjectOptional
Metadata about a property.
availableDocumentTypeslist of objectsOptional
containsPdfFormFieldsstringOptional

When true, the document has editable form fields that are made available through a PDF format.

displaystringOptional

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.

displayMetadataobjectOptional
Metadata about a property.
docGenDocumentStatusstringOptional
docGenErrorslist of objectsOptional
docGenFormFieldslist of objectsOptional
documentBase64stringOptional

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.

documentFieldslist of objectsOptional
An object containing information about the custom fields on the document.
documentIdstringOptional
The ID of the document that the tab is placed on. This value must refer to the ID of an existing document.
documentIdGuidstringOptional
The GUID of the document.
documentTemplateIdstringOptional
errorDetailsobjectOptional
This object describes errors that occur. It is only valid for responses, and ignored in requests.
hasDigitalSignaturestringOptional
includeInDownloadstringOptional

When true, the document is included in the combined document download (documentsCombinedUri). This is only applied to supplemental documents. The default value is true.

includeInDownloadMetadataobjectOptional
Metadata about a property.
isAceGenDocumentstringOptional
isDocGenDocumentstringOptional
isEditedstringOptional
isExternallyAvailablestringOptional
isFlattenedstringOptional
namestringOptional

The document’s file name.

Example: Q1-Report.docx

nameMetadataobjectOptional
Metadata about a property.
orderstringOptional

The order in which to sort the results.

Valid values are:

  • asc: Ascending order.
  • desc: Descending order.
pageslist of objectsOptional
An array of page objects that contain information about the pages in the document.
signerMustAcknowledgestringOptional

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.

signerMustAcknowledgeMetadataobjectOptional
Metadata about a property.
sizeBytesstringOptional
templateLockedstringOptional

When true, the sender cannot change any attributes of the recipient. Used only when working with template recipients.

templateRequiredstringOptional

When true, the sender may not remove the recipient. Used only when working with template recipients.

typestringOptional

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
uristringOptional
The URI for retrieving the document.

Errors

400
Bad Request Error