Adds a document to an existing draft envelope. The bytes of the document make up the body of the request.

Note: When adding or modifying documents for an in-process envelope, DocuSign recommends locking the envelope prior to making any changes.

If the file name of the document contains unicode characters, you need to include a Content-Disposition header. Example:

Header: Content-Disposition

Value: file; filename=\"name\";fileExtension=ext;documentId=1

Request

HTTP request

PUT /v2.1/accounts/{accountId}/envelopes/{envelopeId}/documents/{documentId}

Parameters

Parameter NameValueDescription
Path Parameters
accountIdstring

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

documentIdstring

The documentId is set by the API client. It is an integer that falls between 1 and 2,147,483,647. The value is encoded as a string without commas. The values 1, 2, 3, and so on are typically used to identify the first few documents in an envelope. Tab definitions include a documentId property that specifies the document on which to place the tab.

envelopeIdstring

The envelope's GUID.

Example: 93be49ab-afa0-4adf-933c-f752070d71ec

Responses

CodeDescriptionReference
200

Successful response.

envelopeDocument
400

Error encountered.

errorDetails

SDK Method

Envelopes::updateDocument

Definitions

envelopeDocument

This object contains details about the envelope document.

addedRecipientIds[array]

If recipients were added by converting form fields into tabs, their ids appear here. Read only.

attachmentTabIdstring

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.

authoritativeCopystring

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.

authoritativeCopyMetadatapropertyMetadata

Metadata that indicates if the sender can edit the authoritativeCopy property. Not applicable for template documents.

availableDocumentTypes[signatureType]

containsPdfFormFieldsstring

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

displaystring

This string sets the display and behavior properties of the document during signing. The possible values are:

  • 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.

  • download
    The document is shown as a supplement action strip and can be viewed, downloaded, or printed in a new browser window.

  • 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.

displayMetadatapropertyMetadata

Metadata that indicates if the sender can edit the display property. Not applicable for template documents.

documentFields[nameValue]

An object containing information about the custom fields on the document.

documentGroupstring

The type of group to which the document belongs. Valid values are:

  • content: This is the default value for non-certificate documents.
  • certificate: When a user makes a request to download a certificate of completion, the documents in the certificate document group are appended to the DocuSign certificate and the resulting PDF is returned. Documents returned with the DocuSign certificate are stamped or watermarked to indicate that they were not created by DocuSign.

Note: A document may only be in a single document group.

documentIdstring

The id of the document that the tab is placed on. This value must refer to the id of an existing document.

documentIdGuidstring

The GUID of the document.

errorDetailserrorDetails

This object describes errors that occur. It is only valid for responses and ignored in requests.

includeInDownloadstring

When set to true, the document is included in the combined document download (documentsCombinedUri). The default value is true.

includeInDownloadMetadatapropertyMetadata

Metadata that indicates if the sender can edit the includeInDowload property. Not applicable for template documents.

namestring

The document's file name.

Example: Q1-Report.docx

nameMetadatapropertyMetadata

Metadata that indicates if the sender can edit the name property. Not applicable for template documents.

orderstring

(Optional) The order in which to sort the results.

Valid values are:

  • asc: Ascending order.
  • desc: Descending order.

pages[page]

An array of page objects that contain information about the pages in the document.

signerMustAcknowledgestring

Sets how the signer interacts with the supplemental document. The possible values are:

  • 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.

signerMustAcknowledgeMetadatapropertyMetadata

Metadata that indicates if the sender can edit the signerMustAcknowledge property. Not applicable for template documents.

templateLockedstring

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

templateRequiredstring

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

typestring

uristring

The URI for retrieving the document.

errorDetails

This object describes errors that occur. It is only valid for responses and ignored in requests.

errorCodestring

The code associated with the error condition.

messagestring

A brief message describing the error condition.

nameValue

A name-value pair that describes an item and provides a value for the item.

errorDetailserrorDetails

This object describes errors that occur. It is only valid for responses and ignored in requests.

namestring

The name of the item.

originalValuestring

The initial value of the item.

valuestring

The current value of the item.

page

Description of a page of a document.

dpistring

The number of dots per inch used for the page image.

errorDetailserrorDetails

If an error occurs, this property describes the error.

heightstring

The height of the page in pixels.

imageBytesstring

The number of image bytes.

mimeTypestring

The MIME type.

pageIdstring

The id of the page.

sequencestring

The sequence of the page in the document, or page number.

widthstring

The width of the page in pixels.

propertyMetadata

Metadata about a property.

options[array]

An array of option strings supported by this setting.

rightsstring

Indicates whether the property is editable. Valid values are:

  • editable
  • read_only

signatureType

This object contains information about the type of signature.

isDefaultstring

When true, the signature type is the default type.

typestring

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.

For more information, see Standards Based Signatures.

}} />